<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Security settings in Elasticsearch | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="settings.html" title="Configuring Elasticsearch">
<link rel="prev" href="search-settings.html" title="Search settings">
<link rel="next" href="shard-request-cache.html" title="Shard request cache settings">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="setup.html">Set up Elasticsearch</a></span>
»
<span class="breadcrumb-link"><a href="settings.html">Configuring Elasticsearch</a></span>
»
<span class="breadcrumb-node">Security settings in Elasticsearch</span>
</div>
<div class="navheader">
<span class="prev">
<a href="search-settings.html">« Search settings</a>
</span>
<span class="next">
<a href="shard-request-cache.html">Shard request cache settings »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="security-settings"></a>Security settings in Elasticsearch<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>

<p>By default, the Elasticsearch security features are disabled when you have a basic or
trial license. To enable security features, use the <code class="literal">xpack.security.enabled</code>
setting.</p>
<p>You configure <code class="literal">xpack.security</code> settings to
<a class="xref" href="security-settings.html#anonymous-access-settings" title="Anonymous access settings">enable anonymous access</a> and perform message
authentication,
<a class="xref" href="security-settings.html#field-document-security-settings" title="Document and field level security settings">set up document and field level security</a>,
<a class="xref" href="security-settings.html#realm-settings" title="Realm settings">configure realms</a>,
<a class="xref" href="security-settings.html#ssl-tls-settings" title="General TLS settings">encrypt communications with SSL</a>,and
<a class="xref" href="auditing-settings.html" title="Auditing security settings">audit security events</a>.</p>
<p>All of these settings can be added to the <code class="literal">elasticsearch.yml</code> configuration file,
with the exception of the secure settings, which you add to the Elasticsearch keystore.
For more information about creating and updating the Elasticsearch keystore, see
<a class="xref" href="secure-settings.html" title="Secure settings">Secure settings</a>.</p>
<h4>
<a id="general-security-settings"></a>General security settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h4>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.enabled</code>
</span>
</dt>
<dd>
<p>
Set to <code class="literal">true</code> to enable Elasticsearch security features on the node.<br>
</p>
<p>If set to <code class="literal">false</code>, which is the default value for basic and trial licenses,
security features are disabled. It also affects all Kibana instances that
connect to this Elasticsearch instance; you do not need to disable security features in
those <code class="literal">kibana.yml</code> files. For more information about disabling security features
in specific Kibana instances, see
<a href="/guide/en/kibana/7.7/security-settings-kb.html" class="ulink" target="_top">Kibana security settings</a>.</p>
<div class="tip admon">
<div class="icon"></div>
<div class="admon_content">
<p>If you have gold or higher licenses, the default value is <code class="literal">true</code>; we
recommend that you explicitly add this setting to avoid confusion.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.hide_settings</code>
</span>
</dt>
<dd>
A comma-separated list of settings that are omitted from the results of the
<a class="xref" href="cluster-nodes-info.html" title="Nodes info API">cluster nodes info API</a>. You can use wildcards to include
multiple settings in the list.  For example, the following value hides all the
settings for the ad1 active_directory realm:
<code class="literal">xpack.security.authc.realms.active_directory.ad1.*</code>.
The API already omits all <code class="literal">ssl</code> settings, <code class="literal">bind_dn</code>, and <code class="literal">bind_password</code> due to
the sensitive nature of the information.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.fips_mode.enabled</code>
</span>
</dt>
<dd>
Enables fips mode of operation. Set this to <code class="literal">true</code> if you run this Elasticsearch instance in a FIPS 140-2 enabled JVM.  For more information, see <a class="xref" href="fips-140-compliance.html" title="FIPS 140-2">FIPS 140-2</a>. Defaults to <code class="literal">false</code>.
</dd>
</dl>
</div>
<h4>
<a id="password-hashing-settings"></a>Password hashing settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h4>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.authc.password_hashing.algorithm</code>
</span>
</dt>
<dd>
Specifies the hashing algorithm that is used for secure user credential storage.
See <a class="xref" href="security-settings.html#password-hashing-algorithms" title="Password hashing algorithms">Table 2, “Password hashing algorithms”</a>. Defaults to <code class="literal">bcrypt</code>.
</dd>
</dl>
</div>
<h4>
<a id="anonymous-access-settings"></a>Anonymous access settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h4>
<p>You can configure the following anonymous access settings in
<code class="literal">elasticsearch.yml</code>.  For more information, see <a class="xref" href="anonymous-access.html" title="Enabling anonymous access">Enabling anonymous access</a>.</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.authc.anonymous.username</code>
</span>
</dt>
<dd>
The username (principal) of the anonymous user. Defaults to <code class="literal">_es_anonymous_user</code>.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.authc.anonymous.roles</code>
</span>
</dt>
<dd>
The roles to associate with the anonymous user. Required.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.authc.anonymous.authz_exception</code>
</span>
</dt>
<dd>
When <code class="literal">true</code>, an HTTP 403 response is returned if the anonymous user
does not have the appropriate permissions for the requested action. The
user is not prompted to provide credentials to access the requested
resource. When set to <code class="literal">false</code>, an HTTP 401 response is returned and the user
can provide credentials with the appropriate permissions to gain
access. Defaults to <code class="literal">true</code>.
</dd>
</dl>
</div>
<h4>
<a id="security-automata-settings"></a>Automata Settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h4>
<p>In places where the security features accept wildcard patterns (e.g. index
patterns in roles, group matches in the role mapping API), each pattern is
compiled into an Automaton. The follow settings are available to control this
behaviour.</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.automata.max_determinized_states</code>
</span>
</dt>
<dd>
The upper limit on how many automaton states may be created by a single pattern.
This protects against too-difficult (e.g. exponentially hard) patterns.
Defaults to <code class="literal">100,000</code>.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.automata.cache.enabled</code>
</span>
</dt>
<dd>
Whether to cache the compiled automata. Compiling automata can be CPU intensive
and may slowdown some operations. The cache reduces the frequency with which
automata need to be compiled.
Defaults to <code class="literal">true</code>.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.automata.cache.size</code>
</span>
</dt>
<dd>
The maximum number of items to retain in the automata cache.
Defaults to <code class="literal">10,000</code>.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.automata.cache.ttl</code>
</span>
</dt>
<dd>
The length of time to retain in an item in the automata cache (based on most
recent usage).
Defaults to <code class="literal">48h</code> (48 hours).
</dd>
</dl>
</div>
<h4>
<a id="field-document-security-settings"></a>Document and field level security settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h4>
<p>You can set the following document and field level security
settings in <code class="literal">elasticsearch.yml</code>. For more information, see
<a class="xref" href="field-and-document-access-control.html" title="Setting up field and document level security">Setting up field and document level security</a>.</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.dls_fls.enabled</code>
</span>
</dt>
<dd>
Set to <code class="literal">false</code> to prevent document and field level security
from being configured. Defaults to <code class="literal">true</code>.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.dls.bitset.cache.ttl</code>
</span>
</dt>
<dd>
The time-to-live for cached <code class="literal">BitSet</code> entries for document level security.
Document level security queries may depend on Lucene BitSet objects, and these are
automatically cached to improve performance. Defaults to expire entries that are
unused for <code class="literal">168h</code> (7 days).
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.dls.bitset.cache.size</code>
</span>
</dt>
<dd>
The maximum memory usage of cached <code class="literal">BitSet</code> entries for document level security.
Document level security queries may depend on Lucene BitSet objects, and these are
automatically cached to improve performance. Defaults to <code class="literal">50mb</code>, after which
least-recently-used entries will be evicted.
</dd>
</dl>
</div>
<h4>
<a id="token-service-settings"></a>Token service settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h4>
<p>You can set the following token service settings in
<code class="literal">elasticsearch.yml</code>.</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.authc.token.enabled</code>
</span>
</dt>
<dd>
Set to <code class="literal">false</code> to disable the built-in token service. Defaults to <code class="literal">true</code> unless
 <code class="literal">xpack.security.http.ssl.enabled</code> is <code class="literal">false</code>. This prevents sniffing the token
  from a connection over plain http.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.authc.token.timeout</code>
</span>
</dt>
<dd>
The length of time that a token is valid for. By default this value is <code class="literal">20m</code> or
20 minutes. The maximum value is 1 hour.
</dd>
</dl>
</div>
<h4>
<a id="api-key-service-settings"></a>API key service settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h4>
<p>You can set the following API key service settings in
<code class="literal">elasticsearch.yml</code>.</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.authc.api_key.enabled</code>
</span>
</dt>
<dd>
Set to <code class="literal">false</code> to disable the built-in API key service. Defaults to <code class="literal">true</code> unless
 <code class="literal">xpack.security.http.ssl.enabled</code> is <code class="literal">false</code>. This prevents sniffing the API key
  from a connection over plain http.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.authc.api_key.hashing.algorithm</code>
</span>
</dt>
<dd>
Specifies the hashing algorithm that is used for securing API key credentials.
See <a class="xref" href="security-settings.html#password-hashing-algorithms" title="Password hashing algorithms">Table 2, “Password hashing algorithms”</a>. Defaults to <code class="literal">pbkdf2</code>.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.authc.api_key.cache.ttl</code>
</span>
</dt>
<dd>
The time-to-live for cached API key entries. A API key id and a hash of its
API key are cached for this period of time. Specify the time period using
the standard Elasticsearch <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>. Defaults to <code class="literal">1d</code>.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.authc.api_key.cache.max_keys</code>
</span>
</dt>
<dd>
The maximum number of API key entries that can live in the
cache at any given time. Defaults to 10,000.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.authc.api_key.cache.hash_algo</code>
</span>
</dt>
<dd>
(Expert Setting)
The hashing algorithm that is used for the
in-memory cached API key credentials. For possible values, see <a class="xref" href="security-settings.html#cache-hash-algo" title="Cache hash algorithms">Table 1, “Cache hash algorithms”</a>.
Defaults to <code class="literal">ssha256</code>.
</dd>
</dl>
</div>
<h4>
<a id="realm-settings"></a>Realm settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h4>
<p>You configure realm settings in the <code class="literal">xpack.security.authc.realms</code>
namespace in <code class="literal">elasticsearch.yml</code>. For example:</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">xpack.security.authc.realms:

    native.realm1: <a id="CO24-1"></a><i class="conum" data-value="1"></i>
        order: 0
        ...

    ldap.realm2:
        order: 1
        ...

    active_directory.realm3:
        order: 2
        ...
    ...</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO24-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Specifies the type of realm (for example, <code class="literal">native</code>, <code class="literal">ldap</code>,
<code class="literal">active_directory</code>, <code class="literal">pki</code>, <code class="literal">file</code>, <code class="literal">kerberos</code>, <code class="literal">saml</code>) and the realm name. This
information is required.</p>
</td>
</tr>
</table>
</div>
<p>The valid settings vary depending on the realm type. For more
information, see <a class="xref" href="setting-up-authentication.html" title="User authentication"><em>User authentication</em></a>.</p>
<h5>
<a id="ref-realm-settings"></a>Settings valid for all realms<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">order</code>
</span>
</dt>
<dd>
The priority of the realm within the realm chain. Realms with a lower order are
consulted first. Although not required, use of this setting is strongly
recommended when you configure multiple realms. Defaults to <code class="literal">Integer.MAX_VALUE</code>.
</dd>
<dt>
<span class="term">
<code class="literal">enabled</code>
</span>
</dt>
<dd>
Indicates whether a realm is enabled. You can use this setting to disable a
realm without removing its configuration information. Defaults to <code class="literal">true</code>.
</dd>
</dl>
</div>
<h5>
<a id="ref-native-settings"></a>Native realm settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>For a native realm, the <code class="literal">type</code> must be set to <code class="literal">native</code>. In addition to the
<a class="xref" href="security-settings.html#ref-realm-settings" title="Settings valid for all realms">settings that are valid for all realms</a>, you can specify
the following optional settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">cache.ttl</code>
</span>
</dt>
<dd>
The time-to-live for cached user entries. A user and a hash of its
credentials are cached for this period of time. Specify the time period using
the standard Elasticsearch <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>. Defaults to <code class="literal">20m</code>.
</dd>
<dt>
<span class="term">
<code class="literal">cache.max_users</code>
</span>
</dt>
<dd>
The maximum number of user entries that can live in the
cache at any given time. Defaults to 100,000.
</dd>
<dt>
<span class="term">
<code class="literal">cache.hash_algo</code>
</span>
</dt>
<dd>
(Expert Setting) The hashing algorithm that is used for the
in-memory cached user credentials. For possible values, see <a class="xref" href="security-settings.html#cache-hash-algo" title="Cache hash algorithms">Table 1, “Cache hash algorithms”</a>.
Defaults to <code class="literal">ssha256</code>.
</dd>
<dt>
<span class="term">
<code class="literal">authentication.enabled</code>
</span>
</dt>
<dd>
If set to <code class="literal">false</code>, disables authentication support in
this realm, so that it only supports user lookups.
(See the <a class="xref" href="run-as-privilege.html" title="Submitting requests on behalf of other users">run as</a> and
<a class="xref" href="realm-chains.html#authorization_realms" title="Delegating authorization to another realm">authorization realms</a> features).
Defaults to <code class="literal">true</code>.
</dd>
</dl>
</div>
<h5>
<a id="ref-users-settings"></a>File realm settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>The <code class="literal">type</code> setting must be set to <code class="literal">file</code>. In addition to the
<a class="xref" href="security-settings.html#ref-realm-settings" title="Settings valid for all realms">settings that are valid for all realms</a>, you can specify
the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">cache.ttl</code>
</span>
</dt>
<dd>
The time-to-live for cached user entries. A user and a hash of its credentials
are cached for this configured period of time. Defaults to <code class="literal">20m</code>. Specify values
using the standard Elasticsearch <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>.
Defaults to <code class="literal">20m</code>.
</dd>
<dt>
<span class="term">
<code class="literal">cache.max_users</code>
</span>
</dt>
<dd>
The maximum number of user entries that can live in the cache at a given time.
Defaults to 100,000.
</dd>
<dt>
<span class="term">
<code class="literal">cache.hash_algo</code>
</span>
</dt>
<dd>
(Expert Setting) The hashing algorithm that is used for the in-memory cached
user credentials. See <a class="xref" href="security-settings.html#cache-hash-algo" title="Cache hash algorithms">Table 1, “Cache hash algorithms”</a>. Defaults to <code class="literal">ssha256</code>.
</dd>
<dt>
<span class="term">
<code class="literal">authentication.enabled</code>
</span>
</dt>
<dd>
If set to <code class="literal">false</code>, disables authentication support in
this realm, so that it only supports user lookups.
(See the <a class="xref" href="run-as-privilege.html" title="Submitting requests on behalf of other users">run as</a> and
<a class="xref" href="realm-chains.html#authorization_realms" title="Delegating authorization to another realm">authorization realms</a> features).
Defaults to <code class="literal">true</code>.
</dd>
</dl>
</div>
<h5>
<a id="ref-ldap-settings"></a>LDAP realm settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>The <code class="literal">type</code> setting must be set to <code class="literal">ldap</code>. In addition to the
<a class="xref" href="security-settings.html#ref-realm-settings" title="Settings valid for all realms">Settings valid for all realms</a>, you can specify the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">url</code>
</span>
</dt>
<dd>
<p>
One or more LDAP URLs in the <code class="literal">ldap[s]://&lt;server&gt;:&lt;port&gt;</code> format. Required.
</p>
<p>To provide multiple URLs, use a YAML array (<code class="literal">["ldap://server1:636", "ldap://server2:636"]</code>)
or comma-separated string (<code class="literal">"ldap://server1:636, ldap://server2:636"</code>).</p>
<p>While both are supported, you can’t mix the <code class="literal">ldap</code> and <code class="literal">ldaps</code> protocols.</p>
</dd>
<dt>
<span class="term">
<code class="literal">load_balance.type</code>
</span>
</dt>
<dd>
The behavior to use when there are multiple LDAP URLs defined. For supported
values see <a class="xref" href="security-settings.html#load-balancing" title="Load balancing and failover">load balancing and failover types</a>.
Defaults to <code class="literal">failover</code>.
</dd>
<dt>
<span class="term">
<code class="literal">load_balance.cache_ttl</code>
</span>
</dt>
<dd>
When using <code class="literal">dns_failover</code> or <code class="literal">dns_round_robin</code> as the load balancing type,
this setting controls the amount of time to cache DNS lookups. Defaults
to <code class="literal">1h</code>.
</dd>
<dt>
<span class="term">
<code class="literal">bind_dn</code>
</span>
</dt>
<dd>
The DN of the user that is used to bind to the LDAP and perform searches.
Only applicable in user search mode.
If not specified, an anonymous bind is attempted.
Defaults to Empty. Due to its potential security impact, <code class="literal">bind_dn</code> is not
exposed via the <a class="xref" href="cluster-nodes-info.html" title="Nodes info API">nodes info API</a>.
</dd>
<dt>
<span class="term">
<code class="literal">bind_password</code>
</span>
</dt>
<dd>
<span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">6.3</span>]
<span class="Admonishment-detail">
Deprecated in 6.3.
</span>
</span> Use <code class="literal">secure_bind_password</code> instead. The password for the user
that is used to bind to the LDAP directory.
Defaults to Empty. Due to its potential security impact, <code class="literal">bind_password</code> is not
exposed via the <a class="xref" href="cluster-nodes-info.html" title="Nodes info API">nodes info API</a>.
</dd>
<dt>
<span class="term">
<code class="literal">secure_bind_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the user that is used to bind to the LDAP directory.
Defaults to Empty.
</dd>
<dt>
<span class="term">
<code class="literal">user_dn_templates</code>
</span>
</dt>
<dd>
The DN template that replaces the user name with the string <code class="literal">{0}</code>.
This setting is multivalued; you can specify multiple user contexts.
Required to operate in user template mode. If <code class="literal">user_search.base_dn</code> is specified,
this setting is not valid. For more information on
the different modes, see <a class="xref" href="ldap-realm.html" title="LDAP user authentication">LDAP user authentication</a>.
</dd>
<dt>
<span class="term">
<code class="literal">authorization_realms</code>
</span>
</dt>
<dd>
<p>
The names of the realms that should be consulted for delegated authorization.
If this setting is used, then the LDAP realm does not perform role mapping and
instead loads the user from the listed realms. The referenced realms are
consulted in the order that they are defined in this list.
See <a class="xref" href="realm-chains.html#authorization_realms" title="Delegating authorization to another realm">Delegating authorization to another realm</a>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If any settings starting with <code class="literal">user_search</code> are specified, the
<code class="literal">user_dn_templates</code> settings are ignored.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">user_group_attribute</code>
</span>
</dt>
<dd>
Specifies the attribute to examine on the user for group membership.
If any <code class="literal">group_search</code> settings are specified, this setting is ignored. Defaults
to <code class="literal">memberOf</code>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.base_dn</code>
</span>
</dt>
<dd>
Specifies a container DN to search for users. Required
to operated in user search mode. If <code class="literal">user_dn_templates</code> is specified, this
setting is not valid. For more information on
the different modes, see <a class="xref" href="ldap-realm.html" title="LDAP user authentication">LDAP user authentication</a>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.scope</code>
</span>
</dt>
<dd>
The scope of the user search. Valid values are <code class="literal">sub_tree</code>, <code class="literal">one_level</code> or
<code class="literal">base</code>. <code class="literal">one_level</code> only searches objects directly contained within the
<code class="literal">base_dn</code>. <code class="literal">sub_tree</code> searches all objects contained under <code class="literal">base_dn</code>.
<code class="literal">base</code> specifies that the <code class="literal">base_dn</code> is the user object, and that it is
the only user considered. Defaults to <code class="literal">sub_tree</code>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.filter</code>
</span>
</dt>
<dd>
Specifies the filter used to search the directory in attempts to match
an entry with the username provided by the user. Defaults to <code class="literal">(uid={0})</code>.
<code class="literal">{0}</code> is substituted with the username provided when searching.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.attribute</code>
</span>
</dt>
<dd>
<span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">5.6</span>]
<span class="Admonishment-detail">
Deprecated in 5.6.
</span>
</span> Use <code class="literal">user_search.filter</code> instead.
The attribute to match with the username sent with the request. Defaults to <code class="literal">uid</code>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.pool.enabled</code>
</span>
</dt>
<dd>
Enables or disables connection pooling for user search. If set to <code class="literal">false</code>, a new
connection is created for every search. The
default is <code class="literal">true</code> when <code class="literal">bind_dn</code> is set.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.pool.size</code>
</span>
</dt>
<dd>
The maximum number of connections to the LDAP server to allow in the
connection pool. Defaults to <code class="literal">20</code>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.pool.initial_size</code>
</span>
</dt>
<dd>
The initial number of connections to create to the LDAP server on startup.
Defaults to <code class="literal">0</code>. If the LDAP server is down, values greater than <code class="literal">0</code> could cause
startup failures.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.pool.health_check.enabled</code>
</span>
</dt>
<dd>
Enables or disables a health check on LDAP connections in the connection
pool. Connections are checked in the background at the specified interval.
Defaults to <code class="literal">true</code>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.pool.health_check.dn</code>
</span>
</dt>
<dd>
The distinguished name that is retrieved as part of the health check.
Defaults to the value of <code class="literal">bind_dn</code> if present; if
not, falls back to <code class="literal">user_search.base_dn</code>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.pool.health_check.interval</code>
</span>
</dt>
<dd>
The interval to perform background checks of connections in the pool.
Defaults to <code class="literal">60s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">group_search.base_dn</code>
</span>
</dt>
<dd>
The container DN to search for groups in which the user has membership. When
this element is absent, Elasticsearch searches for the attribute specified by
<code class="literal">user_group_attribute</code> set on the user in order to determine group membership.
</dd>
<dt>
<span class="term">
<code class="literal">group_search.scope</code>
</span>
</dt>
<dd>
Specifies whether the group search should be <code class="literal">sub_tree</code>, <code class="literal">one_level</code> or
<code class="literal">base</code>.  <code class="literal">one_level</code> only searches objects directly contained within the
<code class="literal">base_dn</code>. <code class="literal">sub_tree</code> searches all objects contained under <code class="literal">base_dn</code>.
<code class="literal">base</code> specifies that the <code class="literal">base_dn</code> is a group object, and that it is the
only group considered. Defaults to  <code class="literal">sub_tree</code>.
</dd>
<dt>
<span class="term">
<code class="literal">group_search.filter</code>
</span>
</dt>
<dd>
Specifies a filter to use to look up a group.
When not set, the realm searches for <code class="literal">group</code>, <code class="literal">groupOfNames</code>, <code class="literal">groupOfUniqueNames</code>,
or <code class="literal">posixGroup</code> with the attributes <code class="literal">member</code>, <code class="literal">memberOf</code>, or <code class="literal">memberUid</code>.  Any
instance of <code class="literal">{0}</code> in the filter is replaced by the user attribute defined in
<code class="literal">group_search.user_attribute</code>.
</dd>
<dt>
<span class="term">
<code class="literal">group_search.user_attribute</code>
</span>
</dt>
<dd>
Specifies the user attribute that is fetched and provided as a parameter to
the filter.  If not set, the user DN is passed into the filter. Defaults to Empty.
</dd>
<dt>
<span class="term">
<code class="literal">unmapped_groups_as_roles</code>
</span>
</dt>
<dd>
If set to <code class="literal">true</code>, the names of any unmapped LDAP groups are used as role names
and assigned to the user. A group is considered to be <em>unmapped</em> if it is not
referenced in a <a class="xref" href="mapping-roles.html#mapping-roles-file" title="Using role mapping files">role-mapping file</a>. API-based
role mappings are not considered. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">files.role_mapping</code>
</span>
</dt>
<dd>
The <a class="xref" href="security-files.html" title="Security files">location</a> for the
<a class="xref" href="mapping-roles.html" title="Mapping users and groups to roles">YAML role mapping configuration file</a>. Defaults to
<code class="literal">ES_PATH_CONF/role_mapping.yml</code>.
</dd>
<dt>
<span class="term">
<code class="literal">follow_referrals</code>
</span>
</dt>
<dd>
Specifies whether Elasticsearch should follow referrals returned
by the LDAP server. Referrals are URLs returned by the server that are to be
used to continue the LDAP operation (for example, search). Defaults to <code class="literal">true</code>.
</dd>
<dt>
<span class="term">
<code class="literal">metadata</code>
</span>
</dt>
<dd>
A list of additional LDAP attributes that should be loaded from the
LDAP server and stored in the authenticated user’s metadata field.
</dd>
<dt>
<span class="term">
<code class="literal">timeout.tcp_connect</code>
</span>
</dt>
<dd>
The TCP connect timeout period for establishing an LDAP connection.
An <code class="literal">s</code> at the end indicates seconds, or <code class="literal">ms</code> indicates milliseconds.
Defaults to <code class="literal">5s</code> (5 seconds ).
</dd>
<dt>
<span class="term">
<code class="literal">timeout.tcp_read</code>
</span>
</dt>
<dd>
<span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">7.7</span>]
<span class="Admonishment-detail">
Deprecated in 7.7.
</span>
</span> The TCP read timeout period after establishing an LDAP
connection. This is equivalent to and is deprecated in favor of
<code class="literal">timeout.response</code> and they cannot be used simultaneously. An <code class="literal">s</code> at the end
indicates seconds, or <code class="literal">ms</code> indicates milliseconds.
</dd>
<dt>
<span class="term">
<code class="literal">timeout.response</code>
</span>
</dt>
<dd>
The time interval to wait for the response from the LDAP server. An <code class="literal">s</code> at the
end indicates seconds, or <code class="literal">ms</code> indicates milliseconds. Defaults to the value of
<code class="literal">timeout.ldap_search</code>.
</dd>
<dt>
<span class="term">
<code class="literal">timeout.ldap_search</code>
</span>
</dt>
<dd>
The timeout period for an LDAP search. The value is specified in the request
and is enforced by the receiving LDAP Server.
An <code class="literal">s</code> at the end indicates seconds, or <code class="literal">ms</code> indicates milliseconds.
Defaults to <code class="literal">5s</code> (5 seconds ).
</dd>
<dt>
<span class="term">
<code class="literal">ssl.key</code>
</span>
</dt>
<dd>
<p>
Path to a PEM encoded file containing the private key.
</p>
<p>If the LDAP server requires client authentication, it uses this file. You cannot
use this setting and <code class="literal">ssl.keystore.path</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.key_passphrase</code>
</span>
</dt>
<dd>
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.secure_key_passphrase</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.certificate</code>
</span>
</dt>
<dd>
<p>
Specifies the path for the PEM encoded certificate (or certificate chain) that is
associated with the key.
</p>
<p>This certificate is presented to clients when they connect.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.certificate_authorities</code>
</span>
</dt>
<dd>
<p>
List of paths to PEM encoded certificate files that should be trusted.
</p>
<p>You cannot use this setting and <code class="literal">ssl.truststore.path</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.path</code>
</span>
</dt>
<dd>
<p>
The path for the keystore file that contains a private key and certificate.
</p>
<p>You cannot use this setting and <code class="literal">ssl.key</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.type</code>
</span>
</dt>
<dd>
The format of the keystore file. It must be either <code class="literal">jks</code> or <code class="literal">PKCS12</code>. If the
keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults
to <code class="literal">PKCS12</code>. Otherwise, it defaults to <code class="literal">jks</code>.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.password</code>
</span>
</dt>
<dd>
The password for the keystore.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the keystore.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.key_password</code>
</span>
</dt>
<dd>
The password for the key in the keystore. The default is the keystore password.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.secure_key_password</code>
</span>
</dt>
<dd>
The password for the key in the keystore. The default is the keystore password.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.path</code>
</span>
</dt>
<dd>
<p>
The path for the keystore that contains the certificates to trust. It must be
either a Java keystore (jks) or a PKCS#12 file.
</p>
<p>You cannot use this setting and <code class="literal">ssl.certificate_authorities</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.password</code>
</span>
</dt>
<dd>
The password for the truststore.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
Password for the truststore.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.type</code>
</span>
</dt>
<dd>
The format of the truststore file. For the Java keystore format, use <code class="literal">jks</code>. For
PKCS#12 files, use <code class="literal">PKCS12</code>. For a PKCS#11 token, use <code class="literal">PKCS11</code>. The default is
<code class="literal">jks</code>.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.verification_mode</code>
</span>
</dt>
<dd>
<p>
Indicates the type of verification when using <code class="literal">ldaps</code> to protect against man
in the middle attacks and certificate forgery.
Valid values are:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">full</code>, which verifies that the provided certificate is signed by a trusted
authority (CA) and also verifies that the server’s hostname (or IP address)
matches the names identified within the certificate.
</li>
<li class="listitem">
<code class="literal">certificate</code>, which verifies that the provided certificate is signed by a
trusted authority (CA), but does not perform any hostname verification.
</li>
<li class="listitem">
<p><code class="literal">none</code>, which performs <em>no verification</em> of the server’s certificate. This
mode disables many of the security benefits of SSL/TLS and should only be used
after very careful consideration. It is primarily intended as a temporary
diagnostic mechanism when attempting to resolve TLS errors; its use on
production clusters is strongly discouraged.</p>
<p>The default value is <code class="literal">full</code>.</p>
</li>
</ul>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.supported_protocols</code>
</span>
</dt>
<dd>
<p>
Supported protocols with versions. Valid protocols: <code class="literal">SSLv2Hello</code>,
<code class="literal">SSLv3</code>, <code class="literal">TLSv1</code>, <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code>, <code class="literal">TLSv1.3</code>. If the JVM’s SSL provider supports TLSv1.3,
the default is <code class="literal">TLSv1.3,TLSv1.2,TLSv1.1</code>. Otherwise, the default is
<code class="literal">TLSv1.2,TLSv1.1</code>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If <code class="literal">xpack.security.fips_mode.enabled</code> is <code class="literal">true</code>, you cannot use <code class="literal">SSLv2Hello</code>
or <code class="literal">SSLv3</code>. See <a class="xref" href="fips-140-compliance.html" title="FIPS 140-2">FIPS 140-2</a>.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.cipher_suites</code>
</span>
</dt>
<dd>
<p>
Specifies the cipher suites that should be supported when
communicating with the LDAP server.
Supported cipher suites vary depending on which version of Java you use. For
example, for version 11 the default value is <code class="literal">TLS_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</code>, <code class="literal">TLS_RSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_RSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_RSA_WITH_AES_256_CBC_SHA256</code>,
<code class="literal">TLS_RSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_RSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_RSA_WITH_AES_128_CBC_SHA</code>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The default cipher suites list above includes TLSv1.3 ciphers and ciphers
that require the <em>Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction Policy Files</em> for 256-bit AES encryption. If TLSv1.3 is not
available, the TLSv1.3 ciphers <code class="literal">TLS_AES_256_GCM_SHA384</code> and
<code class="literal">TLS_AES_128_GCM_SHA256</code> are not included in the default list. If 256-bit AES is
unavailable, ciphers with <code class="literal">AES_256</code> in their names are not included in the
default list. Finally, AES GCM has known performance issues in Java versions
prior to 11 and is included in the default list only when using Java 11 or above.</p>
</div>
</div>
<p>For more information, see Oracle’s
<a href="https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2" class="ulink" target="_top">Java Cryptography Architecture documentation</a>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">cache.ttl</code>
</span>
</dt>
<dd>
Specifies the time-to-live for cached user entries. A user and a hash of its
credentials are cached for this period of time. Use the standard Elasticsearch
<a class="xref" href="common-options.html#time-units" title="Time units">time units</a>. Defaults to  <code class="literal">20m</code>.
</dd>
<dt>
<span class="term">
<code class="literal">cache.max_users</code>
</span>
</dt>
<dd>
Specifies the maximum number of user entries that the cache can contain.
Defaults to <code class="literal">100000</code>.
</dd>
<dt>
<span class="term">
<code class="literal">cache.hash_algo</code>
</span>
</dt>
<dd>
(Expert Setting) Specifies the hashing algorithm that is used for the
in-memory cached user credentials. See <a class="xref" href="security-settings.html#cache-hash-algo" title="Cache hash algorithms">Table 1, “Cache hash algorithms”</a>. Defaults to <code class="literal">ssha256</code>.
</dd>
<dt>
<span class="term">
<code class="literal">authentication.enabled</code>
</span>
</dt>
<dd>
If set to <code class="literal">false</code>, disables authentication support in
this realm, so that it only supports user lookups.
(See the <a class="xref" href="run-as-privilege.html" title="Submitting requests on behalf of other users">run as</a> and
<a class="xref" href="realm-chains.html#authorization_realms" title="Delegating authorization to another realm">authorization realms</a> features).
Defaults to <code class="literal">true</code>.
</dd>
</dl>
</div>
<h5>
<a id="ref-ad-settings"></a>Active Directory realm settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>The <code class="literal">type</code> setting must be set to <code class="literal">active_directory</code>. In addition to the
<a class="xref" href="security-settings.html#ref-realm-settings" title="Settings valid for all realms">settings that are valid for all realms</a>, you can specify
the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">url</code>
</span>
</dt>
<dd>
<p>
One or more LDAP URLs in the <code class="literal">ldap[s]://&lt;server&gt;:&lt;port&gt;</code> format. Defaults to
<code class="literal">ldap://&lt;domain_name&gt;:389</code>. This setting is required when connecting using
SSL/TLS or when using a custom port.
</p>
<p>To provide multiple URLs, use a YAML array (<code class="literal">["ldap://server1:636", "ldap://server2:636"]</code>)
or comma-separated string (<code class="literal">"ldap://server1:636, ldap://server2:636"</code>).</p>
<p>While both are supported, you can’t mix the <code class="literal">ldap</code> and <code class="literal">ldaps</code> protocols.</p>
<p>If no URL is provided, Elasticsearch uses a default of <code class="literal">ldap://&lt;domain_name&gt;:389</code>. This
default uses the <code class="literal">domain_name</code> setting value and assumes an unencrypted
connection to port 389.</p>
</dd>
<dt>
<span class="term">
<code class="literal">load_balance.type</code>
</span>
</dt>
<dd>
The behavior to use when there are multiple LDAP URLs defined. For supported
values see <a class="xref" href="security-settings.html#load-balancing" title="Load balancing and failover">load balancing and failover types</a>.
Defaults to <code class="literal">failover</code>.
</dd>
<dt>
<span class="term">
<code class="literal">load_balance.cache_ttl</code>
</span>
</dt>
<dd>
When using <code class="literal">dns_failover</code> or <code class="literal">dns_round_robin</code> as the load balancing type,
this setting controls the amount of time to cache DNS lookups. Defaults
to <code class="literal">1h</code>.
</dd>
<dt>
<span class="term">
<code class="literal">domain_name</code>
</span>
</dt>
<dd>
The domain name of Active Directory. If the <code class="literal">url</code> and the <code class="literal">user_search.base_dn</code>
settings are not specified, the cluster can derive those values from this
setting. Required.
</dd>
<dt>
<span class="term">
<code class="literal">bind_dn</code>
</span>
</dt>
<dd>
The DN of the user that is used to bind to Active Directory and perform searches.
Defaults to Empty. Due to its potential security impact, <code class="literal">bind_dn</code> is not
exposed via the <a class="xref" href="cluster-nodes-info.html" title="Nodes info API">nodes info API</a>.
</dd>
<dt>
<span class="term">
<code class="literal">bind_password</code>
</span>
</dt>
<dd>
<span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">6.3</span>]
<span class="Admonishment-detail">
Deprecated in 6.3.
</span>
</span> Use <code class="literal">secure_bind_password</code> instead. The password for the user
that is used to bind to Active Directory. Defaults to Empty. Due to its
potential security impact, <code class="literal">bind_password</code> is not exposed via the
<a class="xref" href="cluster-nodes-info.html" title="Nodes info API">nodes info API</a>.
</dd>
<dt>
<span class="term">
<code class="literal">secure_bind_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the user that is used to bind to Active Directory.
Defaults to Empty.
</dd>
<dt>
<span class="term">
<code class="literal">unmapped_groups_as_roles</code>
</span>
</dt>
<dd>
If set to <code class="literal">true</code>, the names of any unmapped Active Directory groups are used as
role names and assigned to the user. A group is considered <em>unmapped</em> when it
is not referenced in any role-mapping files. API-based role mappings are not
considered. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">files.role_mapping</code>
</span>
</dt>
<dd>
The <a class="xref" href="security-files.html" title="Security files">location</a> for the YAML
role mapping configuration file. Defaults to <code class="literal">ES_PATH_CONF/role_mapping.yml</code>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.base_dn</code>
</span>
</dt>
<dd>
The context to search for a user. Defaults to the root
of the Active Directory domain.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.scope</code>
</span>
</dt>
<dd>
Specifies whether the user search should be <code class="literal">sub_tree</code>, <code class="literal">one_level</code> or <code class="literal">base</code>.
<code class="literal">one_level</code> only searches users directly contained within the <code class="literal">base_dn</code>.
<code class="literal">sub_tree</code> searches all objects contained under <code class="literal">base_dn</code>. <code class="literal">base</code>
specifies that the <code class="literal">base_dn</code> is a user object, and that it is the
only user considered. Defaults to <code class="literal">sub_tree</code>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.filter</code>
</span>
</dt>
<dd>
Specifies a filter to use to lookup a user given a username.  The default
filter looks up <code class="literal">user</code> objects with either <code class="literal">sAMAccountName</code> or
<code class="literal">userPrincipalName</code>. If specified, this must be a valid LDAP user search filter.
For example <code class="literal">(&amp;(objectClass=user)(sAMAccountName={0}))</code>. For more information,
see
<a href="https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx" class="ulink" target="_top">Search Filter Syntax</a>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.upn_filter</code>
</span>
</dt>
<dd>
Specifies a filter to use to lookup a user given a user principal name.
The default filter looks up <code class="literal">user</code> objects with
a matching <code class="literal">userPrincipalName</code>. If specified, this
must be a valid LDAP user search filter. For example,
<code class="literal">(&amp;(objectClass=user)(userPrincipalName={1}))</code>. <code class="literal">{1}</code> is the full user principal name
provided by the user. For more information, see
<a href="https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx" class="ulink" target="_top">Search Filter Syntax</a>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.down_level_filter</code>
</span>
</dt>
<dd>
Specifies a filter to use to lookup a user given a down level logon name
(DOMAIN\user). The default filter looks up <code class="literal">user</code> objects with a matching
<code class="literal">sAMAccountName</code> in the domain provided. If specified, this
must be a valid LDAP user search filter. For example,
<code class="literal">(&amp;(objectClass=user)(sAMAccountName={0}))</code>. For more information, see
<a href="https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx" class="ulink" target="_top">Search Filter Syntax</a>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.pool.enabled</code>
</span>
</dt>
<dd>
Enables or disables connection pooling for user search. When
disabled a new connection is created for every search. The
default is <code class="literal">true</code> when <code class="literal">bind_dn</code> is provided.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.pool.size</code>
</span>
</dt>
<dd>
The maximum number of connections to the Active Directory server to allow in the
connection pool. Defaults to <code class="literal">20</code>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.pool.initial_size</code>
</span>
</dt>
<dd>
The initial number of connections to create to the Active Directory server on startup.
Defaults to <code class="literal">0</code>. If the LDAP server is down, values greater than 0
could cause startup failures.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.pool.health_check.enabled</code>
</span>
</dt>
<dd>
Enables or disables a health check on Active Directory connections in the connection
pool. Connections are checked in the background at the specified interval.
Defaults to <code class="literal">true</code>.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.pool.health_check.dn</code>
</span>
</dt>
<dd>
The distinguished name to be retrieved as part of the health check.
Defaults to the value of <code class="literal">bind_dn</code> if that setting is present. Otherwise, it
defaults to the value of the <code class="literal">user_search.base_dn</code> setting.
</dd>
<dt>
<span class="term">
<code class="literal">user_search.pool.health_check.interval</code>
</span>
</dt>
<dd>
The interval to perform background checks of connections in the pool.
Defaults to <code class="literal">60s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">group_search.base_dn</code>
</span>
</dt>
<dd>
The context to search for groups in which the user has membership.  Defaults
to the root of the Active Directory domain.
</dd>
<dt>
<span class="term">
<code class="literal">group_search.scope</code>
</span>
</dt>
<dd>
Specifies whether the group search should be <code class="literal">sub_tree</code>, <code class="literal">one_level</code> or
<code class="literal">base</code>.  <code class="literal">one_level</code> searches for groups directly contained within the
<code class="literal">base_dn</code>. <code class="literal">sub_tree</code> searches all objects contained under <code class="literal">base_dn</code>.
<code class="literal">base</code> specifies that the <code class="literal">base_dn</code> is a group object, and that it is
the only group considered. Defaults to <code class="literal">sub_tree</code>.
</dd>
<dt>
<span class="term">
<code class="literal">metadata</code>
</span>
</dt>
<dd>
A list of additional LDAP attributes that should be loaded from the
LDAP server and stored in the authenticated user’s metadata field.
</dd>
<dt>
<span class="term">
<code class="literal">timeout.tcp_connect</code>
</span>
</dt>
<dd>
The TCP connect timeout period for establishing an LDAP connection.
An <code class="literal">s</code> at the end indicates seconds, or <code class="literal">ms</code> indicates milliseconds.
Defaults to <code class="literal">5s</code> (5 seconds ).
</dd>
<dt>
<span class="term">
<code class="literal">timeout.tcp_read</code>
</span>
</dt>
<dd>
<span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">7.7</span>]
<span class="Admonishment-detail">
Deprecated in 7.7.
</span>
</span> The TCP read timeout period after establishing an LDAP
connection.  This is equivalent to and is deprecated in favor of
<code class="literal">timeout.response</code> and they cannot be used simultaneously. An <code class="literal">s</code> at the end
indicates seconds, or <code class="literal">ms</code> indicates milliseconds. Defaults to the value of
<code class="literal">timeout.ldap_search</code>.
</dd>
<dt>
<span class="term">
<code class="literal">timeout.response</code>
</span>
</dt>
<dd>
The time interval to wait for the response from the AD server. An <code class="literal">s</code> at the
end indicates seconds, or <code class="literal">ms</code> indicates milliseconds. Defaults to the value of
<code class="literal">timeout.ldap_search</code>.
</dd>
<dt>
<span class="term">
<code class="literal">timeout.ldap_search</code>
</span>
</dt>
<dd>
The timeout period for an LDAP search. The value is specified in the request
and is enforced by the receiving LDAP Server.
An <code class="literal">s</code> at the end indicates seconds, or <code class="literal">ms</code> indicates milliseconds.
Defaults to <code class="literal">5s</code> (5 seconds ).
</dd>
<dt>
<span class="term">
<code class="literal">ssl.certificate</code>
</span>
</dt>
<dd>
<p>
Specifies the path for the PEM encoded certificate (or certificate chain) that is
associated with the key.
</p>
<p>This certificate is presented to clients when they connect.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.certificate_authorities</code>
</span>
</dt>
<dd>
<p>
List of paths to PEM encoded certificate files that should be trusted.
</p>
<p>You cannot use this setting and <code class="literal">ssl.truststore.path</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.key</code>
</span>
</dt>
<dd>
<p>
Path to a PEM encoded file containing the private key.
</p>
<p>If the Active Directory server requires client authentication, it uses this file.
You cannot use this setting and <code class="literal">ssl.keystore.path</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.key_passphrase</code>
</span>
</dt>
<dd>
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.secure_key_passphrase</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.key_password</code>
</span>
</dt>
<dd>
The password for the key in the keystore. The default is the keystore password.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.secure_key_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the key in the keystore. The default is the keystore password.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.password</code>
</span>
</dt>
<dd>
The password for the keystore.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.secure_keystore.password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the keystore.
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">ssl.keystore.path</code>
</span>
</dt>
<dd>
<p>
The path for the keystore file that contains a private key and certificate.
</p>
<p>You cannot use this setting and <code class="literal">ssl.key</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.type</code>
</span>
</dt>
<dd>
The format of the keystore file. It must be either <code class="literal">jks</code> or <code class="literal">PKCS12</code>. If the
keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults
to <code class="literal">PKCS12</code>. Otherwise, it defaults to <code class="literal">jks</code>.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.password</code>
</span>
</dt>
<dd>
The password for the truststore.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
Password for the truststore.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.path</code>
</span>
</dt>
<dd>
<p>
The path for the keystore that contains the certificates to trust. It must be
either a Java keystore (jks) or a PKCS#12 file.
</p>
<p>You cannot use this setting and <code class="literal">ssl.certificate_authorities</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.type</code>
</span>
</dt>
<dd>
The format of the truststore file. For the Java keystore format, use <code class="literal">jks</code>. For
PKCS#12 files, use <code class="literal">PKCS12</code>. For a PKCS#11 token, use <code class="literal">PKCS11</code>. The default is
<code class="literal">jks</code>.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.verification_mode</code>
</span>
</dt>
<dd>
<p>
Indicates the type of verification when using <code class="literal">ldaps</code> to protect against man
in the middle attacks and certificate forgery.
Valid values are:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">full</code>, which verifies that the provided certificate is signed by a trusted
authority (CA) and also verifies that the server’s hostname (or IP address)
matches the names identified within the certificate.
</li>
<li class="listitem">
<code class="literal">certificate</code>, which verifies that the provided certificate is signed by a
trusted authority (CA), but does not perform any hostname verification.
</li>
<li class="listitem">
<p><code class="literal">none</code>, which performs <em>no verification</em> of the server’s certificate. This
mode disables many of the security benefits of SSL/TLS and should only be used
after very careful consideration. It is primarily intended as a temporary
diagnostic mechanism when attempting to resolve TLS errors; its use on
production clusters is strongly discouraged.</p>
<p>The default value is <code class="literal">full</code>.</p>
</li>
</ul>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.supported_protocols</code>
</span>
</dt>
<dd>
<p>
Supported protocols with versions. Valid protocols: <code class="literal">SSLv2Hello</code>,
<code class="literal">SSLv3</code>, <code class="literal">TLSv1</code>, <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code>, <code class="literal">TLSv1.3</code>. If the JVM’s SSL provider supports TLSv1.3,
the default is <code class="literal">TLSv1.3,TLSv1.2,TLSv1.1</code>. Otherwise, the default is
<code class="literal">TLSv1.2,TLSv1.1</code>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If <code class="literal">xpack.security.fips_mode.enabled</code> is <code class="literal">true</code>, you cannot use <code class="literal">SSLv2Hello</code>
or <code class="literal">SSLv3</code>. See <a class="xref" href="fips-140-compliance.html" title="FIPS 140-2">FIPS 140-2</a>.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.cipher_suites</code>
</span>
</dt>
<dd>
<p>
Specifies the cipher suites that should be supported when
communicating with the Active Directory server.
Supported cipher suites vary depending on which version of Java you use. For
example, for version 11 the default value is <code class="literal">TLS_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</code>, <code class="literal">TLS_RSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_RSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_RSA_WITH_AES_256_CBC_SHA256</code>,
<code class="literal">TLS_RSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_RSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_RSA_WITH_AES_128_CBC_SHA</code>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The default cipher suites list above includes TLSv1.3 ciphers and ciphers
that require the <em>Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction Policy Files</em> for 256-bit AES encryption. If TLSv1.3 is not
available, the TLSv1.3 ciphers <code class="literal">TLS_AES_256_GCM_SHA384</code> and
<code class="literal">TLS_AES_128_GCM_SHA256</code> are not included in the default list. If 256-bit AES is
unavailable, ciphers with <code class="literal">AES_256</code> in their names are not included in the
default list. Finally, AES GCM has known performance issues in Java versions
prior to 11 and is included in the default list only when using Java 11 or above.</p>
</div>
</div>
<p>For more information, see Oracle’s
<a href="https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2" class="ulink" target="_top">Java Cryptography Architecture documentation</a>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">cache.ttl</code>
</span>
</dt>
<dd>
Specifies the time-to-live for cached user entries. A user and a hash of its
credentials are cached for this configured period of time. Use the
standard Elasticsearch <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>).
Defaults to <code class="literal">20m</code>.
</dd>
<dt>
<span class="term">
<code class="literal">cache.max_users</code>
</span>
</dt>
<dd>
Specifies the maximum number of user entries that the cache can contain.
Defaults to <code class="literal">100000</code>.
</dd>
<dt>
<span class="term">
<code class="literal">cache.hash_algo</code>
</span>
</dt>
<dd>
(Expert Setting) Specifies the hashing algorithm that is used for
the in-memory cached user credentials. See <a class="xref" href="security-settings.html#cache-hash-algo" title="Cache hash algorithms">Table 1, “Cache hash algorithms”</a>. Defaults to <code class="literal">ssha256</code>.
</dd>
<dt>
<span class="term">
<code class="literal">authentication.enabled</code>
</span>
</dt>
<dd>
If set to <code class="literal">false</code>, disables authentication support in
this realm, so that it only supports user lookups.
(See the <a class="xref" href="run-as-privilege.html" title="Submitting requests on behalf of other users">run as</a> and
<a class="xref" href="realm-chains.html#authorization_realms" title="Delegating authorization to another realm">authorization realms</a> features).
Defaults to <code class="literal">true</code>.
</dd>
<dt>
<span class="term">
<code class="literal">follow_referrals</code>
</span>
</dt>
<dd>
If set to <code class="literal">true</code>, Elasticsearch follows referrals returned by the LDAP server.
Referrals are URLs returned by the server that are to be used to continue the
LDAP operation (such as <code class="literal">search</code>). Defaults to <code class="literal">true</code>.
</dd>
</dl>
</div>
<h5>
<a id="ref-pki-settings"></a>PKI realm settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>The <code class="literal">type</code> setting must be set to <code class="literal">pki</code>. In addition to the
<a class="xref" href="security-settings.html#ref-realm-settings" title="Settings valid for all realms">settings that are valid for all realms</a>, you can specify
the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">username_pattern</code>
</span>
</dt>
<dd>
The regular expression pattern used to extract the username from the
certificate DN. The first match group is the used as the username.
Defaults to <code class="literal">CN=(.*?)(?:,\|$)</code>.
</dd>
<dt>
<span class="term">
<code class="literal">certificate_authorities</code>
</span>
</dt>
<dd>
List of paths to the PEM certificate files that should be used to authenticate a
user’s certificate as trusted. Defaults to the trusted certificates configured
for SSL. This setting cannot be used with <code class="literal">truststore.path</code>.
</dd>
<dt>
<span class="term">
<code class="literal">truststore.algorithm</code>
</span>
</dt>
<dd>
Algorithm for the truststore. Defaults to <code class="literal">SunX509</code>.
</dd>
<dt>
<span class="term">
<code class="literal">truststore.password</code>
</span>
</dt>
<dd>
The password for the truststore.
</dd>
</dl>
</div>
<p>If <code class="literal">truststore.path</code> is set, this setting is required.</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">truststore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
Password for the truststore.
</dd>
<dt>
<span class="term">
<code class="literal">truststore.path</code>
</span>
</dt>
<dd>
The path of a truststore to use. Defaults to the trusted certificates configured
for SSL. This setting cannot be used with <code class="literal">certificate_authorities</code>.
</dd>
<dt>
<span class="term">
<code class="literal">files.role_mapping</code>
</span>
</dt>
<dd>
Specifies the <a class="xref" href="security-files.html" title="Security files">location</a> of the
<a class="xref" href="mapping-roles.html" title="Mapping users and groups to roles">YAML role  mapping configuration file</a>.
Defaults to <code class="literal">ES_PATH_CONF/role_mapping.yml</code>.
</dd>
<dt>
<span class="term">
<code class="literal">authorization_realms</code>
</span>
</dt>
<dd>
The names of the realms that should be consulted for delegated authorization.
If this setting is used, then the PKI realm does not perform role mapping and
instead loads the user from the listed realms.
See <a class="xref" href="realm-chains.html#authorization_realms" title="Delegating authorization to another realm">Delegating authorization to another realm</a>.
</dd>
<dt>
<span class="term">
<code class="literal">cache.ttl</code>
</span>
</dt>
<dd>
Specifies the time-to-live for cached user entries. A user and a hash of its
credentials are cached for this period of time. Use the
standard Elasticsearch <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>).
Defaults to <code class="literal">20m</code>.
</dd>
<dt>
<span class="term">
<code class="literal">cache.max_users</code>
</span>
</dt>
<dd>
Specifies the maximum number of user entries that the cache can contain.
Defaults to <code class="literal">100000</code>.
</dd>
<dt>
<span class="term">
<code class="literal">delegation.enabled</code>
</span>
</dt>
<dd>
Generally, in order for the clients to be authenticated by the PKI realm they
must connect directly to Elasticsearch. That is, they must not pass through proxies
which terminate the TLS connection. In order to allow for a <span class="strong strong"><strong>trusted</strong></span> and
<span class="strong strong"><strong>smart</strong></span> proxy, such as Kibana, to sit before Elasticsearch and terminate TLS
connections, but still allow clients to be authenticated on Elasticsearch by this realm,
you need to toggle this to <code class="literal">true</code>. Defaults to <code class="literal">false</code>. If delegation is
enabled, then either <code class="literal">truststore.path</code> or <code class="literal">certificate_authorities</code> setting
must be defined. For more details, see <a class="xref" href="pki-realm.html#pki-realm-for-proxied-clients" title="PKI authentication for clients connecting to Kibana">Configuring authentication delegation for PKI realms</a>.
</dd>
</dl>
</div>
<h5>
<a id="ref-saml-settings"></a>SAML realm settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>The <code class="literal">type</code> setting must be set to <code class="literal">saml</code>. In addition to the
<a class="xref" href="security-settings.html#ref-realm-settings" title="Settings valid for all realms">settings that are valid for all realms</a>, you can specify
the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">idp.entity_id</code>
</span>
</dt>
<dd>
The Entity ID of the SAML Identity Provider. An Entity ID is a URI with a
maximum length of 1024 characters. It can be a URL (<a href="https://idp.example.com/" class="ulink" target="_top">https://idp.example.com/</a>) or
a URN (<code class="literal">urn:example.com:idp</code>) and can be found in the configuration or the SAML
metadata of the Identity Provider.
</dd>
<dt>
<span class="term">
<code class="literal">idp.metadata.path</code>
</span>
</dt>
<dd>
The path <em>(recommended)</em> or URL to a SAML 2.0 metadata file describing the
capabilities and configuration of the Identity Provider.
If a path is provided, then it is resolved relative to the Elasticsearch config
directory.
If a URL is provided, then it must be either a <code class="literal">file</code> URL or a <code class="literal">https</code> URL.
Elasticsearch automatically polls this metadata resource and reloads
the IdP configuration when changes are detected.
File based resources are polled at a frequency determined by the global Elasticsearch
<code class="literal">resource.reload.interval.high</code> setting, which defaults to 5 seconds.
HTTPS resources are polled at a frequency determined by the realm’s
<code class="literal">idp.metadata.http.refresh</code> setting.
</dd>
<dt>
<span class="term">
<code class="literal">idp.metadata.http.refresh</code>
</span>
</dt>
<dd>
Controls the frequency with which <code class="literal">https</code> metadata is checked for changes.
Defaults to <code class="literal">1h</code> (1 hour).
</dd>
<dt>
<span class="term">
<code class="literal">idp.use_single_logout</code>
</span>
</dt>
<dd>
Indicates whether to utilise the Identity Provider’s Single Logout service
(if one exists in the IdP metadata file).
Defaults to <code class="literal">true</code>.
</dd>
<dt>
<span class="term">
<code class="literal">sp.entity_id</code>
</span>
</dt>
<dd>
The Entity ID to use for this SAML Service Provider. This should be entered as a
URI. We recommend that you use the base URL of your Kibana instance. For example,
<code class="literal">https://kibana.example.com/</code>.
</dd>
<dt>
<span class="term">
<code class="literal">sp.acs</code>
</span>
</dt>
<dd>
The URL of the Assertion Consumer Service within Kibana. Typically this is the
"api/security/v1/saml" endpoint of your Kibana server. For example,
<code class="literal">https://kibana.example.com/api/security/v1/saml</code>.
</dd>
<dt>
<span class="term">
<code class="literal">sp.logout</code>
</span>
</dt>
<dd>
The URL of the Single Logout service within Kibana. Typically this is the
"logout" endpoint of your Kibana server. For example,
<code class="literal">https://kibana.example.com/logout</code>.
</dd>
<dt>
<span class="term">
<code class="literal">attributes.principal</code>
</span>
</dt>
<dd>
The Name of the SAML attribute that contains the user’s principal (username).
</dd>
<dt>
<span class="term">
<code class="literal">attributes.groups</code>
</span>
</dt>
<dd>
The Name of the SAML attribute that contains the user’s groups.
</dd>
<dt>
<span class="term">
<code class="literal">attributes.name</code>
</span>
</dt>
<dd>
The Name of the SAML attribute that contains the user’s full name.
</dd>
<dt>
<span class="term">
<code class="literal">attributes.mail</code>
</span>
</dt>
<dd>
The Name of the SAML attribute that contains the user’s email address.
</dd>
<dt>
<span class="term">
<code class="literal">attributes.dn</code>
</span>
</dt>
<dd>
The Name of the SAML attribute that contains the user’s X.50
<em>Distinguished Name</em>.
</dd>
<dt>
<span class="term">
<code class="literal">attribute_patterns.principal</code>
</span>
</dt>
<dd>
A Java regular expression that is matched against the SAML attribute specified
by <code class="literal">attributes.pattern</code> before it is applied to the user’s <em>principal</em> property.
The attribute value must match the pattern and the value of the first
<em>capturing group</em> is used as the principal. For example, <code class="literal">^([^@]+)@example\\.com$</code>
matches email addresses from the "example.com" domain and uses the local-part as
the principal.
</dd>
<dt>
<span class="term">
<code class="literal">attribute_patterns.groups</code>
</span>
</dt>
<dd>
As per <code class="literal">attribute_patterns.principal</code>, but for the <em>group</em> property.
</dd>
<dt>
<span class="term">
<code class="literal">attribute_patterns.name</code>
</span>
</dt>
<dd>
As per <code class="literal">attribute_patterns.principal</code>, but for the <em>name</em> property.
</dd>
<dt>
<span class="term">
<code class="literal">attribute_patterns.mail</code>
</span>
</dt>
<dd>
As per <code class="literal">attribute_patterns.principal</code>, but for the <em>mail</em> property.
</dd>
<dt>
<span class="term">
<code class="literal">attribute_patterns.dn</code>
</span>
</dt>
<dd>
As per <code class="literal">attribute_patterns.principal</code>, but for the <em>dn</em> property.
</dd>
<dt>
<span class="term">
<code class="literal">nameid_format</code>
</span>
</dt>
<dd>
The NameID format that should be requested when asking the IdP to authenticate
the current user. Defaults to requesting <em>transient</em> names
(<code class="literal">urn:oasis:names:tc:SAML:2.0:nameid-format:transient</code>).
</dd>
<dt>
<span class="term">
<code class="literal">nameid.allow_create</code>
</span>
</dt>
<dd>
The value of the <code class="literal">AllowCreate</code> attribute of the
<code class="literal">NameIdPolicy</code> element in an authentication request. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">nameid.sp_qualifier</code>
</span>
</dt>
<dd>
The value of the <code class="literal">SPNameQualifier</code> attribute of the
<code class="literal">NameIdPolicy</code> element in an authentication request. The default is to not
include the <code class="literal">SPNameQualifier</code> attribute.
</dd>
<dt>
<span class="term">
<code class="literal">force_authn</code>
</span>
</dt>
<dd>
Specifies whether to set the <code class="literal">ForceAuthn</code> attribute when requesting that the IdP
authenticate the current user. If set to <code class="literal">true</code>, the IdP is required to verify
the user’s identity, irrespective of any existing sessions they might have.
Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">populate_user_metadata</code>
</span>
</dt>
<dd>
Specifies whether to populate the Elasticsearch user’s metadata with the values that are
provided by the SAML attributes. Defaults to <code class="literal">true</code>.
</dd>
<dt>
<span class="term">
<code class="literal">authorization_realms</code>
</span>
</dt>
<dd>
The names of the realms that should be consulted for delegated authorization.
If this setting is used, then the SAML realm does not perform role mapping and
instead loads the user from the listed realms.
See <a class="xref" href="realm-chains.html#authorization_realms" title="Delegating authorization to another realm">Delegating authorization to another realm</a>.
</dd>
<dt>
<span class="term">
<code class="literal">allowed_clock_skew</code>
</span>
</dt>
<dd>
The maximum amount of skew that can be tolerated between the IdP’s clock and the
Elasticsearch node’s clock.
Defaults to <code class="literal">3m</code> (3 minutes).
</dd>
<dt>
<span class="term">
<code class="literal">req_authn_context_class_ref</code>
</span>
</dt>
<dd>
<p>
A comma separated list of Authentication Context Class Reference values to be
included in the Requested Authentication Context when requesting the IdP to
authenticate the current user. The Authentication Context of the corresponding
authentication response should contain at least one of the requested values.
</p>
<p>For more information, see
<a class="xref" href="saml-guide-authentication.html#req-authn-context" title="Requesting specific authentication methods">Requesting specific authentication methods</a>.</p>
</dd>
</dl>
</div>
<h5>
<a id="ref-saml-signing-settings"></a>SAML realm signing settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>If a signing key is configured (that is, either <code class="literal">signing.key</code> or
<code class="literal">signing.keystore.path</code> is set), then Elasticsearch signs outgoing SAML messages.
Signing can be configured using the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">signing.saml_messages</code>
</span>
</dt>
<dd>
A list of SAML message types that should be signed or <code class="literal">*</code> to sign all messages.
Each element in the list should be the local name of a SAML XML Element.
Supported element types are <code class="literal">AuthnRequest</code>, <code class="literal">LogoutRequest</code> and <code class="literal">LogoutResponse</code>.
Only valid if <code class="literal">signing.key</code> or <code class="literal">signing.keystore.path</code> is also specified.
Defaults to <code class="literal">*</code>.
</dd>
<dt>
<span class="term">
<code class="literal">signing.key</code>
</span>
</dt>
<dd>
Specifies the path to the PEM encoded private key to use for SAML message signing.
<code class="literal">signing.key</code> and <code class="literal">signing.keystore.path</code> cannot be used at the same time.
</dd>
<dt>
<span class="term">
<code class="literal">signing.secure_key_passphrase</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
Specifies the passphrase to decrypt the PEM encoded private key (<code class="literal">signing.key</code>)
if it is encrypted.
</dd>
<dt>
<span class="term">
<code class="literal">signing.certificate</code>
</span>
</dt>
<dd>
Specifies the path to the PEM encoded certificate (or certificate chain) that
corresponds to the <code class="literal">signing.key</code>. This certificate must also be included in the
Service Provider metadata or manually configured within the IdP to allow for
signature validation. This setting can only be used if <code class="literal">signing.key</code> is set.
</dd>
<dt>
<span class="term">
<code class="literal">signing.keystore.path</code>
</span>
</dt>
<dd>
The path to the keystore that contains a private key and certificate. It must be
either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
<code class="literal">signing.key</code> at the same time.
</dd>
<dt>
<span class="term">
<code class="literal">signing.keystore.type</code>
</span>
</dt>
<dd>
The type of the keystore in <code class="literal">signing.keystore.path</code>.
Must be either <code class="literal">jks</code> or <code class="literal">PKCS12</code>. If the keystore path ends in ".p12", ".pfx",
or "pkcs12", this setting defaults to <code class="literal">PKCS12</code>. Otherwise, it defaults to <code class="literal">jks</code>.
</dd>
<dt>
<span class="term">
<code class="literal">signing.keystore.alias</code>
</span>
</dt>
<dd>
Specifies the alias of the key within the keystore that should be
used for SAML message signing. If the keystore contains more than one private
key, this setting must be specified.
</dd>
<dt>
<span class="term">
<code class="literal">signing.keystore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password to the keystore in <code class="literal">signing.keystore.path</code>.
</dd>
<dt>
<span class="term">
<code class="literal">signing.keystore.secure_key_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the key in the keystore (<code class="literal">signing.keystore.path</code>).
Defaults to the keystore password.
</dd>
</dl>
</div>
<h5>
<a id="ref-saml-encryption-settings"></a>SAML realm encryption settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>If an encryption key is configured (that is, either <code class="literal">encryption.key</code> or
<code class="literal">encryption.keystore.path</code> is set), then Elasticsearch publishes an encryption
certificate when generating metadata and attempts to decrypt incoming SAML
content. Encryption can be configured using the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">encryption.key</code>
</span>
</dt>
<dd>
Specifies the path to the PEM encoded private key to use for SAML message
decryption.
<code class="literal">encryption.key</code> and <code class="literal">encryption.keystore.path</code> cannot be used at the same time.
</dd>
<dt>
<span class="term">
<code class="literal">encryption.secure_key_passphrase</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
Specifies the passphrase to decrypt the PEM encoded private key
(<code class="literal">encryption.key</code>) if it is encrypted.
</dd>
<dt>
<span class="term">
<code class="literal">encryption.certificate</code>
</span>
</dt>
<dd>
Specifies the path to the PEM encoded certificate (or certificate chain) that is
associated with the <code class="literal">encryption.key</code>. This certificate must also be included in
the Service Provider metadata or manually configured within the IdP to enable
message encryption. This setting can be used only if <code class="literal">encryption.key</code> is set.
</dd>
<dt>
<span class="term">
<code class="literal">encryption.keystore.path</code>
</span>
</dt>
<dd>
The path to the keystore that contains a private key and certificate. It must be
either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
<code class="literal">encryption.key</code> at the same time.
</dd>
<dt>
<span class="term">
<code class="literal">encryption.keystore.type</code>
</span>
</dt>
<dd>
The type of the keystore (<code class="literal">encryption.keystore.path</code>).
Must be either <code class="literal">jks</code> or <code class="literal">PKCS12</code>. If the keystore path ends in ".p12", ".pfx",
or "pkcs12", this setting defaults to <code class="literal">PKCS12</code>. Otherwise, it defaults to <code class="literal">jks</code>.
</dd>
<dt>
<span class="term">
<code class="literal">encryption.keystore.alias</code>
</span>
</dt>
<dd>
Specifies the alias of the key within the keystore (<code class="literal">encryption.keystore.path</code>)
that should be used for SAML message decryption. If not specified, all compatible
key pairs from the keystore are considered as candidate keys for decryption.
</dd>
<dt>
<span class="term">
<code class="literal">encryption.keystore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password to the keystore (<code class="literal">encryption.keystore.path</code>).
</dd>
<dt>
<span class="term">
<code class="literal">encryption.keystore.secure_key_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the key in the keystore (<code class="literal">encryption.keystore.path</code>). Only a
single password is supported. If you are using multiple decryption keys,
they cannot have individual passwords.
</dd>
</dl>
</div>
<h5>
<a id="ref-saml-ssl-settings"></a>SAML realm SSL settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>If you are loading the IdP metadata over SSL/TLS (that is, <code class="literal">idp.metadata.path</code>
is a URL using the <code class="literal">https</code> protocol), the following settings can be used to
configure SSL.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>These settings are not used for any purpose other than loading metadata
over https.</p>
</div>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">ssl.key</code>
</span>
</dt>
<dd>
<p>
Path to a PEM encoded file containing the private key.
</p>
<p>If HTTP client authentication is required, it uses this file. You cannot use
this setting and <code class="literal">ssl.keystore.path</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.key_passphrase</code>
</span>
</dt>
<dd>
<p>
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
</p>
<p>You cannot use this setting and <code class="literal">ssl.secure_key_passphrase</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.secure_key_passphrase</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
<p>
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
</p>
<p>You cannot use this setting and <code class="literal">ssl.key_passphrase</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.certificate</code>
</span>
</dt>
<dd>
<p>
Specifies the path for the PEM encoded certificate (or certificate chain) that is
associated with the key.
</p>
<p>This setting can be used only if <code class="literal">ssl.key</code> is set.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.certificate_authorities</code>
</span>
</dt>
<dd>
<p>
List of paths to PEM encoded certificate files that should be trusted.
</p>
<p>This setting and <code class="literal">ssl.truststore.path</code> cannot be used at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.path</code>
</span>
</dt>
<dd>
<p>
The path for the keystore file that contains a private key and certificate.
</p>
<p>It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this
setting and <code class="literal">ssl.key</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.type</code>
</span>
</dt>
<dd>
The format of the keystore file. It must be either <code class="literal">jks</code> or <code class="literal">PKCS12</code>. If the
keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults
to <code class="literal">PKCS12</code>. Otherwise, it defaults to <code class="literal">jks</code>.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.password</code>
</span>
</dt>
<dd>
<p>
The password for the keystore.
</p>
<p>You cannot use this setting and <code class="literal">ssl.keystore.secure_password</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
<p>
The password for the keystore.
</p>
<p>You cannot use this setting and <code class="literal">ssl.keystore.password</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.key_password</code>
</span>
</dt>
<dd>
<p>
The password for the key in the keystore. The default is the keystore password.
</p>
<p>You cannot use this setting and <code class="literal">ssl.keystore.secure_key_password</code> at the same
time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.secure_key_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the key in the keystore. The default is the keystore password.
</dd>
</dl>
</div>
<p>You cannot use this setting and <code class="literal">ssl.keystore.key_password</code> at the same time.</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">ssl.truststore.path</code>
</span>
</dt>
<dd>
<p>
The path for the keystore that contains the certificates to trust. It must be
either a Java keystore (jks) or a PKCS#12 file.
</p>
<p>You cannot use this setting and <code class="literal">ssl.certificate_authorities</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.type</code>
</span>
</dt>
<dd>
The format of the truststore file. It must be either <code class="literal">jks</code> or <code class="literal">PKCS12</code>. If the
file name ends in ".p12", ".pfx" or "pkcs12", the default is <code class="literal">PKCS12</code>.
Otherwise, it defaults to <code class="literal">jks</code>.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.password</code>
</span>
</dt>
<dd>
<p>
The password for the truststore.
</p>
<p>You cannot use this setting and <code class="literal">ssl.truststore.secure_password</code> at the same
time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
<p>
Password for the truststore.
</p>
<p>This setting cannot be used with <code class="literal">ssl.truststore.password</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.verification_mode</code>
</span>
</dt>
<dd>
<p>
Controls the verification of certificates.
Valid values are:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">full</code>, which verifies that the provided certificate is signed by a trusted
authority (CA) and also verifies that the server’s hostname (or IP address)
matches the names identified within the certificate.
</li>
<li class="listitem">
<code class="literal">certificate</code>, which verifies that the provided certificate is signed by a
trusted authority (CA), but does not perform any hostname verification.
</li>
<li class="listitem">
<p><code class="literal">none</code>, which performs <em>no verification</em> of the server’s certificate. This
mode disables many of the security benefits of SSL/TLS and should only be used
after very careful consideration. It is primarily intended as a temporary
diagnostic mechanism when attempting to resolve TLS errors; its use on
production clusters is strongly discouraged.</p>
<p>The default value is <code class="literal">full</code>.</p>
</li>
</ul>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.supported_protocols</code>
</span>
</dt>
<dd>
<p>
Supported protocols with versions. Valid protocols: <code class="literal">SSLv2Hello</code>,
<code class="literal">SSLv3</code>, <code class="literal">TLSv1</code>, <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code>, <code class="literal">TLSv1.3</code>. If the JVM’s SSL provider supports TLSv1.3,
the default is <code class="literal">TLSv1.3,TLSv1.2,TLSv1.1</code>. Otherwise, the default is
<code class="literal">TLSv1.2,TLSv1.1</code>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If <code class="literal">xpack.security.fips_mode.enabled</code> is <code class="literal">true</code>, you cannot use <code class="literal">SSLv2Hello</code>
or <code class="literal">SSLv3</code>. See <a class="xref" href="fips-140-compliance.html" title="FIPS 140-2">FIPS 140-2</a>.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.cipher_suites</code>
</span>
</dt>
<dd>
<p>
Supported cipher suites vary depending on which version of Java you use. For
example, for version 11 the default value is <code class="literal">TLS_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</code>, <code class="literal">TLS_RSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_RSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_RSA_WITH_AES_256_CBC_SHA256</code>,
<code class="literal">TLS_RSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_RSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_RSA_WITH_AES_128_CBC_SHA</code>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The default cipher suites list above includes TLSv1.3 ciphers and ciphers
that require the <em>Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction Policy Files</em> for 256-bit AES encryption. If TLSv1.3 is not
available, the TLSv1.3 ciphers <code class="literal">TLS_AES_256_GCM_SHA384</code> and
<code class="literal">TLS_AES_128_GCM_SHA256</code> are not included in the default list. If 256-bit AES is
unavailable, ciphers with <code class="literal">AES_256</code> in their names are not included in the
default list. Finally, AES GCM has known performance issues in Java versions
prior to 11 and is included in the default list only when using Java 11 or above.</p>
</div>
</div>
<p>For more information, see Oracle’s
<a href="https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2" class="ulink" target="_top">Java Cryptography Architecture documentation</a>.</p>
</dd>
</dl>
</div>
<h5>
<a id="ref-kerberos-settings"></a>Kerberos realm settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>For a Kerberos realm, the <code class="literal">type</code> must be set to <code class="literal">kerberos</code>. In addition to the
<a class="xref" href="security-settings.html#ref-realm-settings" title="Settings valid for all realms">settings that are valid for all realms</a>, you can specify
the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">keytab.path</code>
</span>
</dt>
<dd>
Specifies the path to the Kerberos keytab file that contains the
service principal used by this Elasticsearch node. This must be a location within the
Elasticsearch configuration directory and the file must have read permissions. Required.
</dd>
<dt>
<span class="term">
<code class="literal">remove_realm_name</code>
</span>
</dt>
<dd>
Set to <code class="literal">true</code> to remove the realm part of principal names.
Principal names in Kerberos have the form <code class="literal">user/instance@REALM</code>. If this option
is <code class="literal">true</code>, the realm part (<code class="literal">@REALM</code>) will not be included in the username.
Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">krb.debug</code>
</span>
</dt>
<dd>
Set to <code class="literal">true</code> to enable debug logs for the Java login module that
provides support for Kerberos authentication. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">cache.ttl</code>
</span>
</dt>
<dd>
The time-to-live for cached user entries. A user is cached for
this period of time. Specify the time period using the standard Elasticsearch
<a class="xref" href="common-options.html#time-units" title="Time units">time units</a>. Defaults to <code class="literal">20m</code>.
</dd>
<dt>
<span class="term">
<code class="literal">cache.max_users</code>
</span>
</dt>
<dd>
The maximum number of user entries that can live in the
cache at any given time. Defaults to 100,000.
</dd>
<dt>
<span class="term">
<code class="literal">authorization_realms</code>
</span>
</dt>
<dd>
The names of the realms that should be consulted for delegated authorization.
If this setting is used, then the Kerberos realm does not perform role mapping and
instead loads the user from the listed realms.
See <a class="xref" href="realm-chains.html#authorization_realms" title="Delegating authorization to another realm">Delegating authorization to another realm</a>.
</dd>
</dl>
</div>
<h5>
<a id="ref-oidc-settings"></a>OpenID Connect realm settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>In addition to the <a class="xref" href="security-settings.html#ref-realm-settings" title="Settings valid for all realms">settings that are valid for all realms</a>, you
can specify the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">op.issuer</code>
</span>
</dt>
<dd>
A verifiable Identifier for your OpenID Connect Provider. An Issuer
Identifier is usually a case sensitive URL using the https scheme that contains
scheme, host, and optionally, port number and path components and no query or
fragment components. The value for this setting should be provided by your OpenID
Connect Provider.
</dd>
<dt>
<span class="term">
<code class="literal">op.authorization_endpoint</code>
</span>
</dt>
<dd>
The URL for the Authorization Endpoint at the
OpenID Connect Provider. The value for this setting should be provided by your OpenID
Connect Provider.
</dd>
<dt>
<span class="term">
<code class="literal">op.token_endpoint</code>
</span>
</dt>
<dd>
The URL for the Token Endpoint at the OpenID Connect Provider.
The value for this setting should be provided by your OpenID Connect Provider.
</dd>
<dt>
<span class="term">
<code class="literal">op.userinfo_endpoint</code>
</span>
</dt>
<dd>
The URL for the User Info Endpoint at the OpenID Connect Provider.
The value for this setting should be provided by your OpenID Connect Provider.
</dd>
<dt>
<span class="term">
<code class="literal">op.endsession_endpoint</code>
</span>
</dt>
<dd>
The URL for the End Session Endpoint at the OpenID Connect
Provider. The value for this setting should be provided by your OpenID Connect Provider.
</dd>
<dt>
<span class="term">
<code class="literal">op.jwkset_path</code>
</span>
</dt>
<dd>
The path or URL to a JSON Web Key Set with the key material that the OpenID Connect
Provider uses for signing tokens and claims responses.
If a path is provided, then it is resolved relative to the Elasticsearch config
directory.
If a URL is provided, then it must be either a <code class="literal">file</code> URL or a <code class="literal">https</code> URL.
Elasticsearch automatically caches the retrieved JWK set to avoid unnecessary HTTP
requests but will attempt to refresh the JWK upon signature verification
failure, as this might indicate that the OpenID Connect Provider has
rotated the signing keys.
</dd>
</dl>
</div>
<p>File based resources are polled at a frequency determined by the global Elasticsearch
<code class="literal">resource.reload.interval.high</code> setting, which defaults to 5 seconds.</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">rp.client_id</code>
</span>
</dt>
<dd>
The OAuth 2.0 Client Identifier that was assigned to Elasticsearch during registration
at the OpenID Connect Provider
</dd>
<dt>
<span class="term">
<code class="literal">rp.client_secret</code>(<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The OAuth 2.0 Client Secret that was assigned to Elasticsearch during registration
at the OpenID Connect Provider
</dd>
<dt>
<span class="term">
<code class="literal">rp.redirect_uri</code>
</span>
</dt>
<dd>
The Redirect URI within Kibana. If you want to use the authorization code flow, this is the
"api/security/oidc/callback" endpoint of your Kibana server. If you want to use the implicit flow,  it is the "api/security/oidc/implicit" endpoint.
For example, <code class="literal">https://kibana.example.com/api/security/oidc/callback</code>.
</dd>
<dt>
<span class="term">
<code class="literal">rp.response_type</code>
</span>
</dt>
<dd>
OAuth 2.0 Response Type value that determines the authorization
processing flow to be used. Can be <code class="literal">code</code> for authorization code grant flow,
or one of <code class="literal">id_token</code>, <code class="literal">id_token token</code> for the implicit flow.
</dd>
<dt>
<span class="term">
<code class="literal">rp.signature_algorithm</code>
</span>
</dt>
<dd>
The signature algorithm that will be used by Elasticsearch in order to verify the
signature of the id tokens it will receive from the OpenID Connect Provider.
Defaults to <code class="literal">RSA256</code>
</dd>
<dt>
<span class="term">
<code class="literal">rp.requested_scopes</code>
</span>
</dt>
<dd>
The scope values that will be requested by the OpenID Connect Provider as
part of the Authentication Request. Optional, defaults to <code class="literal">openid</code>
</dd>
<dt>
<span class="term">
<code class="literal">rp.post_logout_redirect_uri</code>
</span>
</dt>
<dd>
The Redirect URI (usually within Kibana) that the OpenID Connect Provider
should redirect the browser to after a successful Single Logout.
</dd>
<dt>
<span class="term">
<code class="literal">claims.principal</code>
</span>
</dt>
<dd>
The name of the OpenID Connect claim that contains the user’s principal (username).
</dd>
<dt>
<span class="term">
<code class="literal">claims.groups</code>
</span>
</dt>
<dd>
The name of the OpenID Connect claim that contains the user’s groups.
</dd>
<dt>
<span class="term">
<code class="literal">claims.name</code>
</span>
</dt>
<dd>
The name of the OpenID Connect claim that contains the user’s full name.
</dd>
<dt>
<span class="term">
<code class="literal">claims.mail</code>
</span>
</dt>
<dd>
The name of the OpenID Connect claim that contains the user’s email address.
</dd>
<dt>
<span class="term">
<code class="literal">claims.dn</code>
</span>
</dt>
<dd>
The name of the OpenID Connect claim that contains the user’s X.509
<em>Distinguished Name</em>.
</dd>
<dt>
<span class="term">
<code class="literal">claim_patterns.principal</code>
</span>
</dt>
<dd>
A Java regular expression that is matched against the OpenID Connect claim specified
by <code class="literal">claims.principal</code> before it is applied to the user’s <em>principal</em> property.
The attribute value must match the pattern and the value of the first
<em>capturing group</em> is used as the principal. For example, <code class="literal">^([^@]+)@example\\.com$</code>
matches email addresses from the "example.com" domain and uses the local-part as
the principal.
</dd>
<dt>
<span class="term">
<code class="literal">claim_patterns.groups</code>
</span>
</dt>
<dd>
As per <code class="literal">claim_patterns.principal</code>, but for the <em>group</em> property.
</dd>
<dt>
<span class="term">
<code class="literal">claim_patterns.name</code>
</span>
</dt>
<dd>
As per <code class="literal">claim_patterns.principal</code>, but for the <em>name</em> property.
</dd>
<dt>
<span class="term">
<code class="literal">claim_patterns.mail</code>
</span>
</dt>
<dd>
As per <code class="literal">claim_patterns.principal</code>, but for the <em>mail</em> property.
</dd>
<dt>
<span class="term">
<code class="literal">claim_patterns.dn</code>
</span>
</dt>
<dd>
As per <code class="literal">claim_patterns.principal</code>, but for the <em>dn</em> property.
</dd>
<dt>
<span class="term">
<code class="literal">allowed_clock_skew</code>
</span>
</dt>
<dd>
The maximum allowed clock skew to be taken into consideration when validating
id tokens with regards to their creation and expiration times.
</dd>
<dt>
<span class="term">
<code class="literal">populate_user_metadata</code>
</span>
</dt>
<dd>
Specifies whether to populate the Elasticsearch user’s metadata with the values that are
provided by the OpenID Connect claims. Defaults to <code class="literal">true</code>.
</dd>
<dt>
<span class="term">
<code class="literal">http.connect_timeout</code>
</span>
</dt>
<dd>
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the timeout until a connection
 is established. A value of zero means the timeout is not used. Defaults to <code class="literal">5s</code>
</dd>
<dt>
<span class="term">
<code class="literal">http.connection_read_timeout</code>
</span>
</dt>
<dd>
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the timeout used when
requesting a connection from the connection manager. Defaults to <code class="literal">5s</code>
</dd>
<dt>
<span class="term">
<code class="literal">http.socket_timeout</code>
</span>
</dt>
<dd>
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the socket timeout (SO_TIMEOUT)
in milliseconds, which is the timeout for waiting for data or, put differently,
a maximum period inactivity between two consecutive data packets). Defaults to
<code class="literal">5s</code>
</dd>
<dt>
<span class="term">
<code class="literal">http.max_connections</code>
</span>
</dt>
<dd>
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the maximum number of
connections allowed across all endpoints.
</dd>
<dt>
<span class="term">
<code class="literal">http.max_endpoint_connections</code>
</span>
</dt>
<dd>
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the maximum number of
connections allowed per endpoint.
</dd>
</dl>
</div>
<h5>
<a id="ref-oidc-ssl-settings"></a>OpenID Connect realm SSL settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>The following settings can be used to configure SSL for all outgoing http connections
to the OpenID Connect Provider endpoints.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>These settings are <em>only</em> used for the back-channel communication between
Elasticsearch and the OpenID Connect Provider</p>
</div>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">ssl.key</code>
</span>
</dt>
<dd>
<p>
Path to a PEM encoded file containing the private key.
</p>
<p>If HTTP client authentication is required, it uses this file. You cannot use
this setting and <code class="literal">ssl.keystore.path</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.key_passphrase</code>
</span>
</dt>
<dd>
<p>
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
</p>
<p>You cannot use this setting and <code class="literal">ssl.secure_key_passphrase</code> at the same
time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.secure_key_passphrase</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
<p>
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
</p>
<p>You cannot use this setting and <code class="literal">ssl.key_passphrase</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.certificate</code>
</span>
</dt>
<dd>
<p>
Specifies the path for the PEM encoded certificate (or certificate chain) that is
associated with the key.
</p>
<p>This setting can be used only if <code class="literal">ssl.key</code> is set.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.certificate_authorities</code>
</span>
</dt>
<dd>
<p>
List of paths to PEM encoded certificate files that should be trusted.
</p>
<p>This setting and <code class="literal">ssl.truststore.path</code> cannot be used at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.path</code>
</span>
</dt>
<dd>
<p>
The path for the keystore file that contains a private key and certificate.
</p>
<p>It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this
setting and <code class="literal">ssl.key</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.type</code>
</span>
</dt>
<dd>
The format of the keystore file. It must be either <code class="literal">jks</code> or <code class="literal">PKCS12</code>. If the
keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults
to <code class="literal">PKCS12</code>. Otherwise, it defaults to <code class="literal">jks</code>.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.password</code>
</span>
</dt>
<dd>
<p>
The password for the keystore.
</p>
<p>You cannot use this setting and <code class="literal">ssl.keystore.secure_password</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
<p>
The password for the keystore.
</p>
<p>You cannot use this setting and <code class="literal">ssl.keystore.password</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.key_password</code>
</span>
</dt>
<dd>
<p>
The password for the key in the keystore. The default is the keystore password.
</p>
<p>You cannot use this setting and <code class="literal">ssl.keystore.secure_key_password</code> at the same
time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.keystore.secure_key_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
<p>
The password for the key in the keystore. The default is the keystore password.
</p>
<p>You cannot use this setting and <code class="literal">ssl.keystore.key_password</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.path</code>
</span>
</dt>
<dd>
<p>
The path for the keystore that contains the certificates to trust. It must be
either a Java keystore (jks) or a PKCS#12 file.
</p>
<p>You cannot use this setting and <code class="literal">ssl.certificate_authorities</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.type</code>
</span>
</dt>
<dd>
The format of the truststore file. It must be either <code class="literal">jks</code> or <code class="literal">PKCS12</code>. If the
file name ends in ".p12", ".pfx" or "pkcs12", the default is <code class="literal">PKCS12</code>.
Otherwise, it defaults to <code class="literal">jks</code>.
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.password</code>
</span>
</dt>
<dd>
<p>
The password for the truststore.
</p>
<p>You cannot use this setting and <code class="literal">ssl.truststore.secure_password</code> at the same
time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.truststore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
<p>
Password for the truststore.
</p>
<p>You cannot use this setting and <code class="literal">ssl.truststore.password</code> at the same time.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.verification_mode</code>
</span>
</dt>
<dd>
<p>
Controls the verification of certificates.
Valid values are:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">full</code>, which verifies that the provided certificate is signed by a trusted
authority (CA) and also verifies that the server’s hostname (or IP address)
matches the names identified within the certificate.
</li>
<li class="listitem">
<code class="literal">certificate</code>, which verifies that the provided certificate is signed by a
trusted authority (CA), but does not perform any hostname verification.
</li>
<li class="listitem">
<p><code class="literal">none</code>, which performs <em>no verification</em> of the server’s certificate. This
mode disables many of the security benefits of SSL/TLS and should only be used
after very careful consideration. It is primarily intended as a temporary
diagnostic mechanism when attempting to resolve TLS errors; its use on
production clusters is strongly discouraged.</p>
<p>The default value is <code class="literal">full</code>.</p>
</li>
</ul>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.supported_protocols</code>
</span>
</dt>
<dd>
<p>
Supported protocols with versions. Valid protocols: <code class="literal">SSLv2Hello</code>,
<code class="literal">SSLv3</code>, <code class="literal">TLSv1</code>, <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code>, <code class="literal">TLSv1.3</code>. If the JVM’s SSL provider supports TLSv1.3,
the default is <code class="literal">TLSv1.3,TLSv1.2,TLSv1.1</code>. Otherwise, the default is
<code class="literal">TLSv1.2,TLSv1.1</code>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If <code class="literal">xpack.security.fips_mode.enabled</code> is <code class="literal">true</code>, you cannot use <code class="literal">SSLv2Hello</code>
or <code class="literal">SSLv3</code>. See <a class="xref" href="fips-140-compliance.html" title="FIPS 140-2">FIPS 140-2</a>.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">ssl.cipher_suites</code>
</span>
</dt>
<dd>
<p>
Supported cipher suites vary depending on which version of Java you use. For
example, for version 11 the default value is <code class="literal">TLS_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</code>, <code class="literal">TLS_RSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_RSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_RSA_WITH_AES_256_CBC_SHA256</code>,
<code class="literal">TLS_RSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_RSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_RSA_WITH_AES_128_CBC_SHA</code>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The default cipher suites list above includes TLSv1.3 ciphers and ciphers
that require the <em>Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction Policy Files</em> for 256-bit AES encryption. If TLSv1.3 is not
available, the TLSv1.3 ciphers <code class="literal">TLS_AES_256_GCM_SHA384</code> and
<code class="literal">TLS_AES_128_GCM_SHA256</code> are not included in the default list. If 256-bit AES is
unavailable, ciphers with <code class="literal">AES_256</code> in their names are not included in the
default list. Finally, AES GCM has known performance issues in Java versions
prior to 11 and is included in the default list only when using Java 11 or above.</p>
</div>
</div>
<p>For more information, see Oracle’s
<a href="https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2" class="ulink" target="_top">Java Cryptography Architecture documentation</a>.</p>
</dd>
</dl>
</div>
<h5>
<a id="load-balancing"></a>Load balancing and failover<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>The <code class="literal">load_balance.type</code> setting can have the following values:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">failover</code>: The URLs specified are used in the order that they are specified.
The first server that can be connected to will be used for all subsequent
connections. If a connection to that server fails then the next server that a
connection can be established to will be used for subsequent connections.
</li>
<li class="listitem">
<code class="literal">dns_failover</code>: In this mode of operation, only a single URL may be specified.
This URL must contain a DNS name. The system will be queried for all IP
addresses that correspond to this DNS name. Connections to the Active Directory
or LDAP server will always be tried in the order in which they were retrieved.
This differs from <code class="literal">failover</code> in that there is no reordering of the list and if a
server has failed at the beginning of the list, it will still be tried for each
subsequent connection.
</li>
<li class="listitem">
<code class="literal">round_robin</code>: Connections will continuously iterate through the list of
provided URLs. If a server is unavailable, iterating through the list of URLs
will continue until a successful connection is made.
</li>
<li class="listitem">
<code class="literal">dns_round_robin</code>: In this mode of operation, only a single URL may be
specified. This URL must contain a DNS name. The system will be queried for all
IP addresses that correspond to this DNS name. Connections will continuously
iterate through the list of addresses. If a server is unavailable, iterating
through the list of URLs will continue until a successful connection is made.
</li>
</ul>
</div>
<h4>
<a id="ssl-tls-settings"></a>General TLS settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h4>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.ssl.diagnose.trust</code>
</span>
</dt>
<dd>
Controls whether to output diagnostic messages for SSL/TLS trust failures.
If this is <code class="literal">true</code> (the default), a message will be printed to the Elasticsearch
log whenever an SSL connection (incoming or outgoing) is rejected due to a failure
to establish trust.
This diagnostic message contains information that can be used to determine the
cause of the failure and assist with resolving the problem.
Set to <code class="literal">false</code> to disable these messages.
NOTE: This defaults to <code class="literal">false</code> when <code class="literal">xpack.security.fips_mode.enabled</code> is <code class="literal">true</code>.
</dd>
</dl>
</div>
<h5>
<a id="tls-ssl-key-settings"></a>TLS/SSL key and trusted certificate settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>The following settings are used to specify a private key, certificate, and the
trusted certificates that should be used when communicating over an SSL/TLS
connection. If no trusted certificates are configured, the default certificates
that are trusted by the JVM will be trusted along with the certificate(s)
associated with a key in the same context. The key and certificate must be in
place for connections that require client authentication or when acting as a
SSL enabled server.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<a id="pkcs12-truststore-note"></a>
<p>Storing trusted certificates in a PKCS#12 file, although supported, is
uncommon in practice. The <a class="xref" href="certutil.html" title="elasticsearch-certutil"><code class="literal">elasticsearch-certutil</code> tool</a>,
as well as Java’s <code class="literal">keytool</code>, are designed to generate PKCS#12 files that
can be used both as a keystore and as a truststore, but this may not be the
case for container files that are created using other tools. Usually,
PKCS#12 files only contain secret and private entries. To confirm that
a PKCS#12 container includes trusted certificate ("anchor") entries look for
<code class="literal">2.16.840.1.113894.746875.1.1: &lt;Unsupported tag 6&gt;</code> in the
<code class="literal">openssl pkcs12 -info</code> output, or <code class="literal">trustedCertEntry</code> in the
<code class="literal">keytool -list</code> output.</p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="http-tls-ssl-settings"></a>HTTP TLS/SSL settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/ssl-settings.asciidoc">edit</a>
</h3>
</div></div></div>
<p>You can configure the following TLS/SSL settings.</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.enabled</code>
</span>
</dt>
<dd>
Used to enable or disable TLS/SSL. The default is <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.supported_protocols</code>
</span>
</dt>
<dd>
<p>
Supported protocols with versions. Valid protocols: <code class="literal">SSLv2Hello</code>,
<code class="literal">SSLv3</code>, <code class="literal">TLSv1</code>, <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code>, <code class="literal">TLSv1.3</code>. If the JVM’s SSL provider supports TLSv1.3,
the default is <code class="literal">TLSv1.3,TLSv1.2,TLSv1.1</code>. Otherwise, the default is
<code class="literal">TLSv1.2,TLSv1.1</code>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If <code class="literal">xpack.security.fips_mode.enabled</code> is <code class="literal">true</code>, you cannot use <code class="literal">SSLv2Hello</code>
or <code class="literal">SSLv3</code>. See <a class="xref" href="fips-140-compliance.html" title="FIPS 140-2">FIPS 140-2</a>.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.client_authentication</code>
</span>
</dt>
<dd>
Controls the server’s behavior in regard to requesting a certificate
from client connections. Valid values are <code class="literal">required</code>, <code class="literal">optional</code>, and <code class="literal">none</code>.
<code class="literal">required</code> forces a client to present a certificate, while <code class="literal">optional</code>
requests a client certificate but the client is not required to present one.
Defaults to <code class="literal">none</code>.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.cipher_suites</code>
</span>
</dt>
<dd>
<p>
Supported cipher suites vary depending on which version of Java you use. For
example, for version 11 the default value is <code class="literal">TLS_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</code>, <code class="literal">TLS_RSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_RSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_RSA_WITH_AES_256_CBC_SHA256</code>,
<code class="literal">TLS_RSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_RSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_RSA_WITH_AES_128_CBC_SHA</code>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The default cipher suites list above includes TLSv1.3 ciphers and ciphers
that require the <em>Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction Policy Files</em> for 256-bit AES encryption. If TLSv1.3 is not
available, the TLSv1.3 ciphers <code class="literal">TLS_AES_256_GCM_SHA384</code> and
<code class="literal">TLS_AES_128_GCM_SHA256</code> are not included in the default list. If 256-bit AES is
unavailable, ciphers with <code class="literal">AES_256</code> in their names are not included in the
default list. Finally, AES GCM has known performance issues in Java versions
prior to 11 and is included in the default list only when using Java 11 or above.</p>
</div>
</div>
<p>For more information, see Oracle’s
<a href="https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2" class="ulink" target="_top">Java Cryptography Architecture documentation</a>.</p>
</dd>
</dl>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="security-http-tls-ssl-key-trusted-certificate-settings"></a>HTTP TLS/SSL key and trusted certificate settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/ssl-settings.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The following settings are used to specify a private key, certificate, and the
trusted certificates that should be used when communicating over an SSL/TLS connection.
A private key and certificate must be configured.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_pem_encoded_files_2"></a>PEM encoded files<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/ssl-settings.asciidoc">edit</a>
</h4>
</div></div></div>
<p>When using PEM encoded files, use the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.key</code>
</span>
</dt>
<dd>
Path to a PEM encoded file containing the private key.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.key_passphrase</code>
</span>
</dt>
<dd>
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.secure_key_passphrase</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.certificate</code>
</span>
</dt>
<dd>
Specifies the path for the PEM encoded certificate (or certificate chain) that is
associated with the key.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.certificate_authorities</code>
</span>
</dt>
<dd>
List of paths to PEM encoded certificate files that should be trusted.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_java_keystore_files_2"></a>Java keystore files<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/ssl-settings.asciidoc">edit</a>
</h4>
</div></div></div>
<p>When using Java keystore files (JKS), which contain the private key, certificate
and certificates that should be trusted, use the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.keystore.path</code>
</span>
</dt>
<dd>
The path for the keystore file that contains a private key and certificate.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.keystore.password</code>
</span>
</dt>
<dd>
The password for the keystore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.keystore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the keystore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.keystore.key_password</code>
</span>
</dt>
<dd>
The password for the key in the keystore. The default is the keystore password.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.keystore.secure_key_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the key in the keystore. The default is the keystore password.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.truststore.path</code>
</span>
</dt>
<dd>
The path for the keystore that contains the certificates to trust. It must be
either a Java keystore (jks) or a PKCS#12 file.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.truststore.password</code>
</span>
</dt>
<dd>
The password for the truststore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.truststore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
Password for the truststore.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="security-http-pkcs12-files"></a>PKCS#12 files<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/ssl-settings.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Elasticsearch can be configured to use PKCS#12 container files (<code class="literal">.p12</code> or <code class="literal">.pfx</code> files)
that contain the private key, certificate and certificates that should be trusted.</p>
<p>PKCS#12 files are configured in the same way as Java keystore files:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.keystore.path</code>
</span>
</dt>
<dd>
The path for the keystore file that contains a private key and certificate.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.keystore.type</code>
</span>
</dt>
<dd>
The format of the keystore file. It must be either <code class="literal">jks</code> or <code class="literal">PKCS12</code>. If the
keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults
to <code class="literal">PKCS12</code>. Otherwise, it defaults to <code class="literal">jks</code>.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.keystore.password</code>
</span>
</dt>
<dd>
The password for the keystore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.keystore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the keystore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.keystore.key_password</code>
</span>
</dt>
<dd>
The password for the key in the keystore. The default is the keystore password.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.keystore.secure_key_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the key in the keystore. The default is the keystore password.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.truststore.path</code>
</span>
</dt>
<dd>
The path for the keystore that contains the certificates to trust. It must be
either a Java keystore (jks) or a PKCS#12 file.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.truststore.type</code>
</span>
</dt>
<dd>
Set this to <code class="literal">PKCS12</code> to indicate that the truststore is a PKCS#12 file.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.truststore.password</code>
</span>
</dt>
<dd>
The password for the truststore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.ssl.truststore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
Password for the truststore.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="security-http-pkcs11-tokens"></a>PKCS#11 tokens<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/ssl-settings.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Elasticsearch can be configured to use a PKCS#11 token that contains the private key,
certificate and certificates that should be trusted.</p>
<p>PKCS#11 token require additional configuration on the JVM level and can be enabled
via the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.http.keystore.type</code>
</span>
</dt>
<dd>
Set this to <code class="literal">PKCS11</code> to indicate that the PKCS#11 token should be used as a keystore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.truststore.type</code>
</span>
</dt>
<dd>
The format of the truststore file. For the Java keystore format, use <code class="literal">jks</code>. For
PKCS#12 files, use <code class="literal">PKCS12</code>. For a PKCS#11 token, use <code class="literal">PKCS11</code>. The default is
<code class="literal">jks</code>.
</dd>
</dl>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>When configuring the PKCS#11 token that your JVM is configured to use as
a keystore or a truststore for Elasticsearch, the PIN for the token can be
configured by setting the appropriate value to <code class="literal">ssl.truststore.password</code>
or <code class="literal">ssl.truststore.secure_password</code> in the context that you are configuring.
Since there can only be one PKCS#11 token configured, only one keystore and
truststore will be usable for configuration in Elasticsearch. This in turn means
that only one certificate can be used for TLS both in the transport and the
http layer.</p>
</div>
</div>
</div>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="transport-tls-ssl-settings"></a>Transport TLS/SSL settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/ssl-settings.asciidoc">edit</a>
</h3>
</div></div></div>
<p>You can configure the following TLS/SSL settings.</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.enabled</code>
</span>
</dt>
<dd>
Used to enable or disable TLS/SSL. The default is <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.supported_protocols</code>
</span>
</dt>
<dd>
<p>
Supported protocols with versions. Valid protocols: <code class="literal">SSLv2Hello</code>,
<code class="literal">SSLv3</code>, <code class="literal">TLSv1</code>, <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code>, <code class="literal">TLSv1.3</code>. If the JVM’s SSL provider supports TLSv1.3,
the default is <code class="literal">TLSv1.3,TLSv1.2,TLSv1.1</code>. Otherwise, the default is
<code class="literal">TLSv1.2,TLSv1.1</code>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If <code class="literal">xpack.security.fips_mode.enabled</code> is <code class="literal">true</code>, you cannot use <code class="literal">SSLv2Hello</code>
or <code class="literal">SSLv3</code>. See <a class="xref" href="fips-140-compliance.html" title="FIPS 140-2">FIPS 140-2</a>.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.client_authentication</code>
</span>
</dt>
<dd>
Controls the server’s behavior in regard to requesting a certificate
from client connections. Valid values are <code class="literal">required</code>, <code class="literal">optional</code>, and <code class="literal">none</code>.
<code class="literal">required</code> forces a client to present a certificate, while <code class="literal">optional</code>
requests a client certificate but the client is not required to present one.
Defaults to <code class="literal">none</code>.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.verification_mode</code>
</span>
</dt>
<dd>
<p>
Controls the verification of certificates.
Valid values are:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">full</code>, which verifies that the provided certificate is signed by a trusted
authority (CA) and also verifies that the server’s hostname (or IP address)
matches the names identified within the certificate.
</li>
<li class="listitem">
<code class="literal">certificate</code>, which verifies that the provided certificate is signed by a
trusted authority (CA), but does not perform any hostname verification.
</li>
<li class="listitem">
<p><code class="literal">none</code>, which performs <em>no verification</em> of the server’s certificate. This
mode disables many of the security benefits of SSL/TLS and should only be used
after very careful consideration. It is primarily intended as a temporary
diagnostic mechanism when attempting to resolve TLS errors; its use on
production clusters is strongly discouraged.</p>
<p>The default value is <code class="literal">full</code>.</p>
</li>
</ul>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.cipher_suites</code>
</span>
</dt>
<dd>
<p>
Supported cipher suites vary depending on which version of Java you use. For
example, for version 11 the default value is <code class="literal">TLS_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</code>, <code class="literal">TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</code>, <code class="literal">TLS_RSA_WITH_AES_256_GCM_SHA384</code>,
<code class="literal">TLS_RSA_WITH_AES_128_GCM_SHA256</code>, <code class="literal">TLS_RSA_WITH_AES_256_CBC_SHA256</code>,
<code class="literal">TLS_RSA_WITH_AES_128_CBC_SHA256</code>, <code class="literal">TLS_RSA_WITH_AES_256_CBC_SHA</code>,
<code class="literal">TLS_RSA_WITH_AES_128_CBC_SHA</code>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The default cipher suites list above includes TLSv1.3 ciphers and ciphers
that require the <em>Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction Policy Files</em> for 256-bit AES encryption. If TLSv1.3 is not
available, the TLSv1.3 ciphers <code class="literal">TLS_AES_256_GCM_SHA384</code> and
<code class="literal">TLS_AES_128_GCM_SHA256</code> are not included in the default list. If 256-bit AES is
unavailable, ciphers with <code class="literal">AES_256</code> in their names are not included in the
default list. Finally, AES GCM has known performance issues in Java versions
prior to 11 and is included in the default list only when using Java 11 or above.</p>
</div>
</div>
<p>For more information, see Oracle’s
<a href="https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2" class="ulink" target="_top">Java Cryptography Architecture documentation</a>.</p>
</dd>
</dl>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="security-transport-tls-ssl-key-trusted-certificate-settings"></a>Transport TLS/SSL key and trusted certificate settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/ssl-settings.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The following settings are used to specify a private key, certificate, and the
trusted certificates that should be used when communicating over an SSL/TLS connection.
A private key and certificate must be configured.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_pem_encoded_files_3"></a>PEM encoded files<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/ssl-settings.asciidoc">edit</a>
</h4>
</div></div></div>
<p>When using PEM encoded files, use the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.key</code>
</span>
</dt>
<dd>
Path to a PEM encoded file containing the private key.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.key_passphrase</code>
</span>
</dt>
<dd>
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.secure_key_passphrase</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.certificate</code>
</span>
</dt>
<dd>
Specifies the path for the PEM encoded certificate (or certificate chain) that is
associated with the key.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.certificate_authorities</code>
</span>
</dt>
<dd>
List of paths to PEM encoded certificate files that should be trusted.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_java_keystore_files_3"></a>Java keystore files<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/ssl-settings.asciidoc">edit</a>
</h4>
</div></div></div>
<p>When using Java keystore files (JKS), which contain the private key, certificate
and certificates that should be trusted, use the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.keystore.path</code>
</span>
</dt>
<dd>
The path for the keystore file that contains a private key and certificate.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.keystore.password</code>
</span>
</dt>
<dd>
The password for the keystore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.keystore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the keystore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.keystore.key_password</code>
</span>
</dt>
<dd>
The password for the key in the keystore. The default is the keystore password.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.keystore.secure_key_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the key in the keystore. The default is the keystore password.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.truststore.path</code>
</span>
</dt>
<dd>
The path for the keystore that contains the certificates to trust. It must be
either a Java keystore (jks) or a PKCS#12 file.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.truststore.password</code>
</span>
</dt>
<dd>
The password for the truststore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.truststore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
Password for the truststore.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="security-transport-pkcs12-files"></a>PKCS#12 files<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/ssl-settings.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Elasticsearch can be configured to use PKCS#12 container files (<code class="literal">.p12</code> or <code class="literal">.pfx</code> files)
that contain the private key, certificate and certificates that should be trusted.</p>
<p>PKCS#12 files are configured in the same way as Java keystore files:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.keystore.path</code>
</span>
</dt>
<dd>
The path for the keystore file that contains a private key and certificate.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.keystore.type</code>
</span>
</dt>
<dd>
The format of the keystore file. It must be either <code class="literal">jks</code> or <code class="literal">PKCS12</code>. If the
keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults
to <code class="literal">PKCS12</code>. Otherwise, it defaults to <code class="literal">jks</code>.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.keystore.password</code>
</span>
</dt>
<dd>
The password for the keystore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.keystore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the keystore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.keystore.key_password</code>
</span>
</dt>
<dd>
The password for the key in the keystore. The default is the keystore password.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.keystore.secure_key_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
The password for the key in the keystore. The default is the keystore password.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.truststore.path</code>
</span>
</dt>
<dd>
The path for the keystore that contains the certificates to trust. It must be
either a Java keystore (jks) or a PKCS#12 file.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.truststore.type</code>
</span>
</dt>
<dd>
Set this to <code class="literal">PKCS12</code> to indicate that the truststore is a PKCS#12 file.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.truststore.password</code>
</span>
</dt>
<dd>
The password for the truststore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.ssl.truststore.secure_password</code> (<a class="xref" href="secure-settings.html" title="Secure settings">Secure</a>)
</span>
</dt>
<dd>
Password for the truststore.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="security-transport-pkcs11-tokens"></a>PKCS#11 tokens<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/ssl-settings.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Elasticsearch can be configured to use a PKCS#11 token that contains the private key,
certificate and certificates that should be trusted.</p>
<p>PKCS#11 token require additional configuration on the JVM level and can be enabled
via the following settings:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.transport.keystore.type</code>
</span>
</dt>
<dd>
Set this to <code class="literal">PKCS11</code> to indicate that the PKCS#11 token should be used as a keystore.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.truststore.type</code>
</span>
</dt>
<dd>
The format of the truststore file. For the Java keystore format, use <code class="literal">jks</code>. For
PKCS#12 files, use <code class="literal">PKCS12</code>. For a PKCS#11 token, use <code class="literal">PKCS11</code>. The default is
<code class="literal">jks</code>.
</dd>
</dl>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>When configuring the PKCS#11 token that your JVM is configured to use as
a keystore or a truststore for Elasticsearch, the PIN for the token can be
configured by setting the appropriate value to <code class="literal">ssl.truststore.password</code>
or <code class="literal">ssl.truststore.secure_password</code> in the context that you are configuring.
Since there can only be one PKCS#11 token configured, only one keystore and
truststore will be usable for configuration in Elasticsearch. This in turn means
that only one certificate can be used for TLS both in the transport and the
http layer.</p>
</div>
</div>
<h5>
<a id="ssl-tls-profile-settings"></a>Transport profile TLS/SSL settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h5>
<p>The same settings that are available for the <a class="xref" href="security-settings.html#transport-tls-ssl-settings" title="Transport TLS/SSL settings">default transport</a>
are also available for each transport profile. By default, the settings for a
transport profile will be the same as the default transport unless they
are specified.</p>
<p>As an example, lets look at the key setting. For the default transport
this is <code class="literal">xpack.security.transport.ssl.key</code>. In order to use this setting in a
transport profile, use the prefix <code class="literal">transport.profiles.$PROFILE.xpack.security.</code> and
append the portion of the setting after <code class="literal">xpack.security.transport.</code>. For the key
setting, this would be <code class="literal">transport.profiles.$PROFILE.xpack.security.ssl.key</code>.</p>
<h4>
<a id="ip-filtering-settings"></a>IP filtering settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-settings.asciidoc">edit</a>
</h4>
<p>You can configure the following settings for <a class="xref" href="ip-filtering.html" title="Restricting connections with IP filtering">IP filtering</a>.</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">xpack.security.transport.filter.allow</code>
</span>
</dt>
<dd>
List of IP addresses to allow.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.transport.filter.deny</code>
</span>
</dt>
<dd>
List of IP addresses to deny.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.filter.allow</code>
</span>
</dt>
<dd>
List of IP addresses to allow just for HTTP.
</dd>
<dt>
<span class="term">
<code class="literal">xpack.security.http.filter.deny</code>
</span>
</dt>
<dd>
List of IP addresses to deny just for HTTP.
</dd>
<dt>
<span class="term">
<code class="literal">transport.profiles.$PROFILE.xpack.security.filter.allow</code>
</span>
</dt>
<dd>
List of IP addresses to allow for this profile.
</dd>
<dt>
<span class="term">
<code class="literal">transport.profiles.$PROFILE.xpack.security.filter.deny</code>
</span>
</dt>
<dd>
List of IP addresses to deny for this profile.
</dd>
</dl>
</div>
<h4>
<a id="hashing-settings"></a>User cache and password hash algorithms<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/settings/security-hash-settings.asciidoc">edit</a>
</h4>
<p>Certain realms store user credentials in memory. To limit exposure
to credential theft and mitigate credential compromise, the cache only stores
a hashed version of the user credentials in memory. By default, the user cache
is hashed with a salted <code class="literal">sha-256</code> hash algorithm. You can use a different
hashing algorithm by setting the <code class="literal">cache.hash_algo</code> realm settings to any of the
following values:</p>
<div class="table">
<a id="cache-hash-algo"></a>
<p class="title"><strong>Table 1. Cache hash algorithms</strong></p>
<div class="table-contents">
<table border="1" cellpadding="4px" summary="Cache hash algorithms">
<colgroup>
<col class="col_1">
<col class="col_2">
<col class="col_3">
<col class="col_4">
</colgroup>
<tbody>
<tr>
<td align="left" valign="top"><p>Algorithm</p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Description</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">ssha256</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses a salted <code class="literal">sha-256</code> algorithm (default).</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">md5</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">MD5</code> algorithm.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">sha1</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">SHA1</code> algorithm.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 1024 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt4</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 16 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt5</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 32 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt6</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 64 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt7</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 128 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt8</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 256 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt9</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 512 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                             pseudorandom function using 10000 iterations.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2_1000</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                             pseudorandom function using 1000 iterations.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2_10000</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                             pseudorandom function using 10000 iterations.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2_50000</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                             pseudorandom function using 50000 iterations.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2_100000</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                             pseudorandom function using 100000 iterations.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2_500000</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                              pseudorandom function using 500000 iterations.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2_1000000</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                             pseudorandom function using 1000000 iterations.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">noop</code>,<code class="literal">clear_text</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Doesn’t hash the credentials and keeps it in clear text in
                            memory. CAUTION: keeping clear text is considered insecure
                            and can be compromised at the OS level (for example through
                            memory dumps and using <code class="literal">ptrace</code>).</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<p>Likewise, realms that store passwords hash them using cryptographically strong
and password-specific salt values. You can configure the algorithm for password
hashing by setting the <code class="literal">xpack.security.authc.password_hashing.algorithm</code> setting
to one of the following:</p>
<div class="table">
<a id="password-hashing-algorithms"></a>
<p class="title"><strong>Table 2. Password hashing algorithms</strong></p>
<div class="table-contents">
<table border="1" cellpadding="4px" summary="Password hashing algorithms">
<colgroup>
<col class="col_1">
<col class="col_2">
<col class="col_3">
<col class="col_4">
</colgroup>
<thead>
<tr>
<th align="left" valign="top">Algorithm</th>
<th align="left" valign="top"></th>
<th align="left" valign="top"></th>
<th align="left" valign="top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 1024 rounds. (default)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt4</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 16 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt5</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 32 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt6</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 64 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt7</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 128 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt8</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 256 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt9</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 512 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt10</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 1024 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt11</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 2048 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt12</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 4096 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt13</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 8192 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">bcrypt14</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">bcrypt</code> algorithm with salt generated in 16384 rounds.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                             pseudorandom function using 10000 iterations.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2_1000</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                             pseudorandom function using 1000 iterations.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2_10000</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                             pseudorandom function using 10000 iterations.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2_50000</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                             pseudorandom function using 50000 iterations.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2_100000</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                             pseudorandom function using 100000 iterations.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2_500000</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                              pseudorandom function using 500000 iterations.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">pbkdf2_1000000</code></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p></p></td>
<td align="left" valign="top"><p>Uses <code class="literal">PBKDF2</code> key derivation function with <code class="literal">HMAC-SHA512</code> as a
                             pseudorandom function using 1000000 iterations.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>

</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="search-settings.html">« Search settings</a>
</span>
<span class="next">
<a href="shard-request-cache.html">Shard request cache settings »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
